yonote-mcp

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation3/5
Many tools have distinct resource+action naming, but there is direct overlap between documents_star/unstar and stars_create/delete, which both manage favorites. Additionally, documents_archive, documents_delete, and documents_restore have fuzzy boundaries (delete moves to trash, archive hides, restore applies to both). With 110 tools, agents may struggle to pick the correct tool for similar operations.
Naming Consistency4/5
Most tools follow a resource_action pattern (e.g., documents_list, documents_create, users_delete). However, some tools use noun-only names for list operations (loop_teams, loop_channels, telegram_commands), and the mix of verbs like 'get' vs 'info' is handled consistently but with the occasional 'add_user' vs 'remove_user' for memberships. Overall, the pattern is recognizable but not uniform.
Tool Count1/5
110 tools is an extreme outlier for an MCP server. This is far beyond the typical 3-15 tool range and even above 50, making navigation and selection unwieldy for agents. It suggests the server exposes the entire API surface rather than a curated set.
Completeness3/5
The tool set covers many domains: documents, collections, users, comments, shares, stars, revisions, attachments, auth, and integrations. However, there are lifecycle gaps: no explicit publish tool (only documents_unpublish), and no permanent delete (only move to trash). The database and sync features are minimally exposed, suggesting some features are underdeveloped.
Average 3.2/5 across 90 of 110 tools scored. Lowest: 1.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under GPL 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Export a document' reveals no side effects, return format, authentication needs, or whether it is a read-only operation. This is effectively a blank slate with zero 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise in length, but it is under-specified. It lacks the content needed to be useful, similar to the 'Under-specification, not conciseness' example. The sentence does not earn its place because it conveys almost no actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a terse description, this tool is severely underspecified. An agent cannot determine when to use it, what output to expect, or how it behaves. For a tool with only two parameters (both optional) and a generic verb, the description is completely inadequate for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters ('id' and 'shareId') with descriptions, so schema coverage is 100%. The description adds no meaning beyond what the schema already provides. Per policy, baseline is 3 when schema coverage is high, and there is no additional parameter clarification to raise it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Export a document.' merely restates the tool name in sentence form. It provides no details about what export entails (e.g., format, destination, or scope), and it does not distinguish from sibling export tools like collections_export. This is essentially a tautology, similar to the 'Process' example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, common use cases, or contrasts with related operations such as documents_download or collections_export. An agent is left without any 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects, permissions, output format, or whether this is a read-only or mutating operation. The phrase 'Export a collection' gives no insight into what actually happens.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short and has no wasted words, it is under-specified to the point of being unhelpful. It resembles a placeholder rather than a well-crafted concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, the tool's behavior, return value, and use case are entirely unexplained. For a simple tool it might be acceptable, but the description lacks even basic context about what 'export' entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the id parameter described as 'Collection ID'. The description adds no additional meaning beyond the schema, but the schema already provides sufficient information for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Export') and resource ('a collection'), which is clear enough to understand the basic purpose. However, it does not differentiate from sibling tools like collections_export_all, and the exact meaning of 'export' (file download, data format, etc.) is left vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context is provided about prerequisites, typical scenarios, or how it relates to collections_export_all or other collection tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'List file operations' with no mention of pagination behavior, sorting, output format, whether it is read-only, or any side effects. This is a significant gap for a tool with six parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions 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 unnecessary words, making it very concise. However, it is on the edge of under-specification given the tool's parameter richness, so it does not earn a perfect 5. The structure is simple and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with 6 parameters and no output schema, yet the description provides only the bare minimum. It does not explain the pagination parameters (limit, offset, nextPath), the meaning of 'file operations', or what the response looks like. This leaves important context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, with each of the six parameters having a description (e.g., 'Operation type (e.g. export, import)', 'Number of results'). The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('List') and a resource ('file operations'), which distinguishes it from sibling tools like file_operations_info and file_operations_redirect. However, 'file operations' is somewhat vague, leaving the exact nature of the listed items open to interpretation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention any use case, prerequisites, or exclusions, and there is no reference to sibling tools. The simple verb 'list' provides no context for when this should be preferred over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden, but it only restates 'Update' without disclosing mutation effects, permission requirements, partial update semantics, or idempotency. It adds no information beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence, which is economical but lacks substance. It does not add value beyond what the tool name implies, making it minimally adequate but not well-structured for decision-making.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with no annotations and no output schema, the description is insufficient. It does not explain return values, side effects, partial update behavior, or any caveats, leaving the agent without crucial context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage), so the baseline is 3. The description mentions only 'properties' generically and does not add meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a collection's properties, which is specific and distinct from siblings like collections_create, collections_list, and collections_info. However, it doesn't enumerate the properties or add context beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 collections_create or collections_info. There are no prerequisites, exclusions, or contextual hints to help an agent decide.
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 carries the full burden of behavioral transparency. It states only 'Login via LDAP' without disclosing side effects (e.g., session creation), security implications, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, in one short phrase. It doesn't waste words, but it is under-specified, earning a mid-range score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three required parameters and no output schema; the description offers no information about return values, authentication outcomes, or required preconditions. This is insufficient for a complex auth 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?
All three parameters have schema descriptions with 100% coverage, so the schema already documents email, password, and providerId. The description adds no additional meaning beyond re-stating the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a verb ('Login') and a resource ('LDAP'), conveying it authenticates a user via LDAP. However, it lacks any detail about the authentication flow or how it differs from related auth tools like auth_info or ldap_ping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 neither names alternative tools nor specifies conditions under which LDAP login is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not explain whether converting a document into a template modifies the original, creates a new entity, requires permissions, or has any side effects. The term 'convert' is ambiguous, and no further behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately front-loaded and easy to read, although it could benefit from more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the domain (with many sibling document tools) and the lack of annotations or output schema, the description is insufficiently complete. It does not explain what a template is, how conversion affects the original, or what the result looks like, leaving significant ambiguity for a one-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 has 100% coverage with a single parameter 'id' described as 'Document ID.' The description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Convert a document into a template' clearly identifies the action (convert) and the resource (document into a template). It distinguishes itself from sibling tools by introducing a unique templating operation not present in other 'documents_*' tool names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided about when to use this tool versus alternatives such as documents_create or documents_update. The description offers no context, prerequisites, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for disclosing behavioral traits. It does not indicate whether deletion is permanent, whether it requires permissions, if it cascades to related data, or what the response looks like. This is a significant transparency gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It earns its place, though it is minimal in content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a delete operation with no annotations, no output schema, and two optional parameters, the description is incomplete. It does not explain how ids and documentId interact, nor does it describe the outcome or side 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?
The schema descriptions already cover 100% of the parameters ('Block IDs' and 'Document ID'), so the baseline is 3. The description adds no additional meaning or relationship between the two 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 ('Delete') and the resource ('sync blocks'), which distinguishes it from sibling tools like sync_blocks_create and sync_blocks_list. However, it provides no additional scope or detail about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus other sync block tools, nor does it mention any prerequisites or conditions. There is no contextual cue for the AI agent to decide when to invoke delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only says 'test', implying a non-mutating check, but it does not specify whether this performs a bind, search, or simple connectivity check, nor what output to expect. This is insufficient for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded with the core intent. However, for a tool with 8 parameters and no other documentation, it is under-specified and could have used an additional sentence to clarify the tool's role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the description is far too minimal. It does not explain the purpose of the test, the semantics of the parameters, or what a successful or failed connection means. This is inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 8 parameters with individual descriptions, and schema description coverage is 100%. The tool description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Test LDAP connection' clearly states the action (test) and resource (LDAP connection). It is a specific verb+resource pair, but it does not distinguish this tool from sibling tools like ldap_login, which also involve connecting to LDAP, so it lacks the differentiation needed for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 gives no context, prerequisites, or exclusions, leaving the agent without criteria for selecting this tool among LDAP-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'create,' implying a mutation, but gives no details on permissions, side effects, idempotency, or response behavior. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, containing no wasted words, but it is under-specified. It provides a clear verb-object pair but omits any context or caveats. This is efficient yet minimal, bordering on insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters, no output schema, and no annotations. The description does not explain what sync blocks are, the relationship between ids and documentId, or the expected outcome. This is inadequate for a create operation in a domain with 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?
The input schema covers 100% of parameters (ids and documentId each have descriptions), so the baseline is 3. The description itself adds no parameter-level meaning, but the schema already documents the fields adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create sync blocks' clearly states the action (create) and the resource (sync blocks). It is not a tautology and distinguishes the tool from non-sync-block siblings, though it does not differentiate it from sync_blocks_delete or sync_blocks_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like sync_blocks_delete or sync_blocks_list. There is no mention of prerequisites, context, or exclusions, so the agent is left 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 behavioral disclosure. It only says 'List sync blocks' and does not mention whether the operation is read-only, what data is returned, whether there are any side effects, or how the results are structured. The term 'sync blocks' is unexplained, limiting the agent's understanding of expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action, containing no wasted words. However, it is under-specified for a tool with a specialized concept like 'sync blocks'. The simplicity is fine, but combined with the lack of context, it borders on too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's one parameter and no output schema, the description could be adequate for a very simple list operation. However, the presence of sibling 'sync_blocks_list_inserts' indicates nuance that is not addressed. There is no context on what sync blocks are, what distinguishes them from inserts, or how to interpret the results. The description feels incomplete for an agent needing to make an informed call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (documentId) with 100% description coverage in the schema ('Document ID'). The tool description does not add any additional meaning beyond the schema, so the baseline score of 3 applies. There is no extra semantic value, 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?
The description clearly states a specific verb ('List') and resource ('sync blocks') for a document. However, it does not distinguish from the sibling tool 'sync_blocks_list_inserts', which also lists sync-related blocks but specifically inserts. The description is unambiguous about the core operation but lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'sync_blocks_list_inserts' or other document list tools. The description gives no context for selecting this tool, which leaves the agent to guess the intended use case.
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 carries the full burden of behavioral disclosure. It only states 'Record a document view' without mentioning side effects, idempotency, permissions, or whether it creates a duplicate each time. This is comparable to the update_drive example where mutation details are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but the brevity results in under-specification. While there is no wasted text, the tool could benefit from additional context, making it minimally adequate but not ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations, no output schema, and a 4-word description. The agent is left without information on return values, side effects, or how this interacts with related tools. Given the low complexity, this is still a significant 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?
The schema covers the single parameter 'documentId' with a description, meaning 100% coverage. The tool description adds no extra meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Record a document view' uses a specific verb ('Record') and a clear resource ('document view'), indicating a write operation that logs a view. It distinguishes itself from sibling 'views_list' by implying an action rather than a listing, though it could be slightly ambiguous whether it creates a saved view or logs an event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 'documents_viewed' or 'views_list'. There is no mention of prerequisites, exclusions, or contextual triggers.
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 only says 'get detailed information' without disclosing the exact return shape, potential errors, authentication needs, or whether the operation is read-only. This is insufficient for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions 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 fluff. It is appropriately minimal for a simple info tool, though it could have included a bit more context about the returned data without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description fails to specify what 'detailed information' includes or how it differs from other collection-level info tools. The agent cannot fully anticipate the tool's behavior or response format, making it incomplete for reliable selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter 'id' with 'Collection ID', so schema coverage is 100%. The description adds no extra context about the id, such as where to find it or format expectations, which is acceptable given the schema already covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('get') and resource ('collection'), and 'detailed information' signals a singular item lookup. However, it does not explicitly distinguish from sibling tools like collections_list or collections_documents, so it slightly misses the bar for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The description simply states the action without contextual advice, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral traits beyond the action itself. It doesn't mention authentication requirements, side effects, or return value, leaving the agent to infer.
Agents need to know what a tool does to the world before calling it. Descriptions 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, efficiently stating the core purpose. However, it errs on the side of under-specification rather than being concisely complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 no annotations and no output schema, the description provides only minimal context. It doesn't explain what entity types are valid, whether parentCommentId is optional for replies, or what the tool returns, making it incomplete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for all four parameters, so the description adds no additional parameter semantics. The example in the description mirrors the schema's example for entityType.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('add a comment') and provides an example entityType, distinguishing it from sibling comment tools like comments_list, comments_update, and comments_delete. However, 'entity' remains generic without enumerating supported entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives; it simply states the action. There's no mention of when to use replies (parentCommentId) or differences from comments_thread.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states a read operation and does not mention authentication needs, handling of deleted comments via the paranoid parameter, or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler words. It is appropriately front-loaded, though it may be slightly too sparse to be fully informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a minimal description, the tool lacks context about return values, behavior, or the significance of the paranoid flag. For a 2-parameter info tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters (id and paranoid) with descriptions, and schema coverage is 100%. The description adds no extra meaning beyond what the schema provides, so the 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 uses the specific verb 'Get' and resource 'comment', clearly identifying this as a single-comment info retrieval tool. It distinguishes from siblings like comments_list and comments_thread by focusing on a specific comment, though 'information' is somewhat generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 comments_list or comments_thread. There are no explicit exclusions or contextual hints to help the agent choose correctly.
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 must disclose behavioral traits on its own. It does not mention pagination behavior, return format, necessary permissions, or any side effects. The presence of pagination parameters (limit/offset/nextPath) is left unaddressed, leaving the agent under-informed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and provides a useful example. It is appropriately concise with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a paginated list tool with no output schema, so the description needs to explain how to use parameters like entityId and pagination. It does not, and the example only shows entityType, which may mislead an agent into thinking entityId is optional. The lack of return value description further reduces 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%, so the baseline is 3. The description adds an example for entityType but does not clarify entityId or the pagination flow. The schema descriptions for each parameter are present but shallow, and the tool description does not compensate for these gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 comments') and the resource ('for an entity'), with a concrete example for entityType. It distinguishes the basic purpose from create/update/delete/resolve siblings, but does not explicitly differentiate from comments_info or comments_thread, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like comments_thread or comments_info. The description only states what it does without providing context for choosing it over siblings or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist to cover safety or side effects. The description only states 'Resolve a comment thread' without disclosing what changes occur, whether the action is idempotent, or if special permissions are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise and front-loaded. It may be under-specified, but for a simple one-parameter tool, brevity is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and lack of output schema, the description is minimal but lacks contextual detail about the action's effects and return values. The absence of behavioral context makes it incomplete for an agent to fully understand the tool's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single 'id' parameter with 'Comment ID' (100% coverage). The description does not add any parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Resolve' and identifies the resource 'a comment thread,' making the action clear. However, it does not elaborate on what resolving entails, so it doesn't fully distinguish from comments_update which might also modify thread state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description gives no indication of when to prefer comments_resolve over related tools like comments_update or comments_delete, nor does it mention 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?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention return format, pagination behavior, whether deleted comments are included, or authentication requirements. The phrase 'Get a comment thread' is purely nominal.
Agents need to know what a tool does to the world before calling it. Descriptions 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. Its brevity is acceptable for a simple getter, though it could have added valuable 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?
The tool has 5 parameters, no output schema, and no annotations, yet the description offers no insight into thread structure, pagination semantics (limit, offset, nextPath), or the paranoid parameter. An agent would be under-informed about the response and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 5 parameters are documented in the schema, meeting the baseline of 3. The description adds no additional parameter context, but the schema already provides full property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a comment thread' clearly states a specific verb and resource, distinguishing it from siblings like comments_list and comments_info. However, it doesn't elaborate on what constitutes a thread versus a list, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternative comment tools (e.g., comments_list, comments_info). The description lacks any statement of exclusions, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not state that the operation is read-only, mention pagination, return format, or any side effects. For a list operation, the read-only nature is implied but not explicit, and no other behavioral context is offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, but it is also under-specified; a bit more context on filtering or sorting would improve usefulness without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description provides no context about return values, filtering/sorting capabilities, or how it relates to sibling tools. The description is too sparse to be considered complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all properties are already documented in the input schema. The description adds no extra meaning beyond the schema, which aligns with the baseline of 3 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 identifies the verb (List) and resource (rows in a database document), making the primary purpose obvious. However, it does not differentiate from sibling tools like documents_list or database_transaction, so it lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context for appropriate use, and no exclusions or prerequisites. It is a bare statement of functionality without any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states the action without mentioning permission levels, idempotency, whether existing permissions are overwritten, authentication requirements, or any side effects. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is properly front-loaded and minimal, though it lacks additional context that would belong in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations, no output schema, and a terse description. While the schema fully documents the input parameters, the description does not provide enough context about the operation's behavior, such as what happens on success, whether permissions are additive, or how it differs from collection-level grants. For an agent to use it reliably, more behavioral detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters (id, userId, permission) with descriptions and a permission enum, giving schema coverage of 100%. Since the schema already documents the parameters, the description need not repeat them; however, it also adds no additional semantic context beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'grant' with the resource 'a user access to a document,' clearly indicating the action. It distinguishes from the sibling tool documents_remove_user, which revokes access, and from collections_add_user, which targets collections rather than documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as documents_remove_user or collections_add_user. There are no prerequisites, exclusions, or context for when this tool is appropriate, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden. It only states the basic listing action and does not disclose pagination behavior, result format, or any other operational traits. The read-only nature is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that is appropriately concise and contains no extraneous words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 optional parameters and the absence of an output schema, the description is insufficient. It does not mention supported filters, pagination options, or return payload details, leaving significant gaps for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 7 parameters (sort, limit, offset, etc.) having descriptions in the schema. The description adds no additional parameter information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List' with a specific resource 'draft documents' scoped to 'current user'. It implicitly differentiates from sibling tools like documents_list by specifying drafts, but does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus documents_list or other listing tools. The description gives only the core action, with no mention of appropriate contexts 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?
With no annotations, the description must fully disclose behavior. It only says 'List documents' and mentions filters, but fails to mention pagination (limit/offset), sorting, default behavior, or that this is a read-only operation. Key behavioral aspects like how 'other criteria' map to parameters are left entirely to the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and easy to parse. The two-sentence format is efficient, though the phrase 'or other criteria' adds little information and could be more specific. It is appropriately sized, but not maximally 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?
For a tool with 10 optional parameters and no output schema or annotations, the description is too thin. It does not explain pagination, sorting, return value structure, or how this list operation differs from search. The lack of any guidance on typical usage or edge cases leaves significant gaps 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%, and each parameter already has a description. The tool description adds minimal semantic value by naming 'collection, user' which maps to collectionId and userId, but 'other criteria' is vague and does not enhance understanding beyond the schema. The baseline 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List), resource (documents), and scope (filterable). It is unambiguous and appropriate for a listing tool. However, it does not explicitly distinguish from sibling tools like documents_search or documents_search_titles, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as documents_search, documents_children, or documents_drafts. The phrase 'or other criteria' vaguely implies broad filtering but does not specify use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It adds minimal context beyond the tool name ('in its collection') but does not explain side effects, reversibility, permissions, or impact on document ordering. This is only slightly more informative than a tautology.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and contains no unnecessary words. It succinctly states the action and object, achieving maximum brevity without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with one parameter, the description lacks essential context about the pinning behavior, its relationship to unpinning, and the meaning of 'in its collection'. Given no annotations or output schema, the description should provide more operational context, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 'id' parameter already documented as 'Document ID'. The description adds no additional parameter semantics, but the schema provides sufficient meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pin') and resource ('a document'), with the context 'in its collection' adding scope. While it doesn't explicitly distinguish from sibling tools like documents_star or documents_unpin, the verb 'pin' is specific enough to convey the core 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. There is no mention of conditions, prerequisites, or contrast with documents_unpin or documents_pinned. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states the action but fails to mention idempotency, user scope, permission requirements, or whether the star is reversible. This leaves the agent without critical operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of four words, perfectly concise and front-loaded. No filler exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a mutation with no annotations and no output schema, the description is too sparse. It lacks behavioral details (e.g., effect of starring an already-starred document) and usage alternatives, making it contextually incomplete despite the simple parameter set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the 'id' parameter as 'Document ID' (100% coverage), so the description adds no additional parameter semantics. It meets the baseline but provides no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Star') and identifies the resource ('document'), making the core action clear. However, it does not explicitly differentiate from sibling tools like stars_create or documents_starred, though the name implies document-specific starring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as documents_unstar or stars_create, nor any prerequisites or contextual cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read operation ('get information') but does not state whether errors occur for invalid IDs, what the response structure is, or whether it has side effects. For a simple info tool, this is minimal but still lacks key behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the essential action. Every word earns its place, and there is no verbosity or irrelevant detail. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema), the description is still insufficient. It does not explain what information is returned, how to handle errors, or how this tool relates to the broader file operations group. Without an output schema or annotations, the description should provide more context but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers the single parameter 'id' with the description 'File operation ID', so schema coverage is 100%. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate—the parameter is adequately documented but the description does not enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get information about a file operation' clearly identifies the action (get information) and resource (file operation), which differentiates it from the sibling 'file_operations_list' (which lists operations) and 'file_operations_redirect' (which redirects). It is specific enough for an informational tool, though it could mention that it retrieves details for a specific operation by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like file_operations_list or file_operations_redirect. It does not mention prerequisites, such as needing a valid operation ID, or when a user should choose this over other file operation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, and the description provides no behavioral detail beyond the basic action. It does not mention authentication requirements, likely responses, or side effects such as duplicate name handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no irrelevant content. It is appropriately minimal for a simple create operation, though it lacks depth in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 lack of annotations and an output schema, the description is insufficiently complete. It fails to indicate return values, error conditions, or operational prerequisites, and it does not differentiate behavior from closely related group 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?
The input schema fully describes the single 'name' parameter with a clear description (100% coverage), so the schema carries the parameter semantics. The description adds no additional parameter information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and clearly identifies the resource as 'a new user group', distinguishing it from sibling tools like groups_update and groups_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as groups_add_user or groups_update. There are no prerequisites, exclusions, or contextual hints 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?
With no annotations, the description carries full responsibility for behavioral disclosure. It does not mention whether the operation is destructive, reversible, requires permissions, or what happens if the user is not in the group. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the operation. It is front-loaded with the primary action and uses no unnecessary words, making it efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple, the description lacks completeness for a mutation operation. There is no information about return values, errors, prerequisites, or behavioral effects, and the absence of annotations increases the burden on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for both parameters (Group ID and User ID) with 100% coverage. The description adds no extra meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: removing a user from a group, with a specific verb and resource. It is distinguishable from the sibling tool groups_add_user, which is the inverse operation. However, it lacks explicit detail about the context of group membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided. The description does not mention alternatives, prerequisites, or when this should be used over other tools like groups_memberships or groups_info. The intended usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It indicates a mutating action ('post') but fails to disclose side effects, permissions, rate limits, or the nature of the update being posted. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy, but the brevity borders on under-specification. It is concise yet lacks any supporting context, so it is not well-structured for an agent to understand the tool's full scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two fully documented parameters, the description covers the basic purpose. However, it does not explain what happens after posting, what constitutes a 'collection update', or any behavioral outcome. With no annotations or output schema, key aspects remain unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described ('Channel to post to', 'Collection ID'). The description adds context by framing the action as a 'collection update', linking the two params, but does not add format, syntax, or relationship details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Post' and identifies the resource as 'a collection update' to 'Loop'. It distinguishes from document/collection tools, but the phrase 'collection update' is somewhat ambiguous and does not clarify how it differs from sibling Loop tools like loop_channels or loop_commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any prerequisites, exclusions, or context. It simply states the action without any directive.
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?
There are no annotations, so the description carries the full burden. It only says 'list', implying a read operation, but does not disclose pagination behavior, sorting defaults, limits, or any side effects. It also does not mention whether it requires a document identifier from context or how results are ordered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence that is front-loaded with the key action and resource. There is no waste or redundancy, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, yet the description is extremely terse. It does not explain the structure of version history entries, pagination handling, or how the document is identified, making it inadequate for a tool with 5 parameters and no other context. The missing document identifier is a severe 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?
The input schema already describes all 5 parameters (sort, limit, offset, nextPath, direction) with brief descriptions, and the description adds no additional parameter context. However, a critical document identifier is absent from the schema, making it unclear how the document is specified. Since schema coverage is 100%, baseline is 3, and the description does not compensate for the missing document reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 version history of a document' clearly states the action (list) and resource (version history of a document), and it distinguishes from sibling revisions_info which likely fetches a single revision. However, it does not clarify which document is being referenced, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives like revisions_info or documents_list. It does not mention any prerequisites or context requirements, so the agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only offers the generic phrase 'Get information'. It does not disclose what information is returned, whether a share ID or document ID is required, or any read-only guarantees beyond the verb 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to stating the basic purpose, making it appropriately concise for a simple info tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, this tool description is too sparse. The two optional parameters create ambiguity about which identifier is required, and the description does not clarify the return value or any operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters ('Share ID' and 'Document ID'), so baseline is 3. The tool description adds no further meaning about how these parameters relate or when to use each, leaving the agent with schema-only knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Get') and resource ('share link'), making its basic purpose obvious. However, it does not distinguish this from the sibling tool shares_list, which also deals with share information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as shares_list, shares_create, or shares_update. The description gives no context about prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 'List shared documents' without mentioning return format, pagination behavior, permissions, or side effects. This adds minimal value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It effectively communicates the primary purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, this description is inadequate. It fails to explain the meaning of 'shared documents', the response structure, how parameters like sort/limit/offset/nextPath interact, or how it differs from similar 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?
The input schema has 100% description coverage for all five parameters, so the schema already documents each one. The description does not add any additional parameter semantics, yielding the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a resource ('shared documents'), making the core action clear. However, it doesn't explicitly differentiate it from sibling tools like documents_list or shares_info, so there is some ambiguity about whether it returns share records or documents that are shared.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 documents_list or shares_info. The description lacks any context about intended use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Update' implies mutation, but it doesn't state whether it's a partial update, what happens to unspecified properties, whether special permissions are needed, or what the response looks like. 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 a single focused sentence that conveys the core purpose with no fluff. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has six parameters and is a mutation operation, yet the description is just one sentence. It lacks update semantics (e.g., partial vs. full update), prerequisites, or consequences. With no annotations or output schema, the description needs more context to be 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 100% coverage with descriptive parameter details (e.g., 'Custom link slug,' 'Expire at date (ISO 8601)'). The description adds no parameter meaning, but the schema does the heavy lifting, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a share link's properties, using a specific verb and resource. This distinguishes it from sibling tools like shares_create, shares_revoke, shares_list, and shares_info, though it doesn't enumerate the exact properties being updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention that it's for modifying existing shares, nor does it point to shares_create for new shares or shares_revoke for revoking access. The only cue is the verb 'update.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description bears full responsibility for disclosing behavioral effects. 'Subscribe' implies a state change, but there is no detail on permissions required, whether subscriptions are idempotent, what the return value is, or how to manage the subscription afterward. Minimal disclosure beyond the bare 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, clear sentence with no wasted words. It is front-loaded and appropriately sized for a simple tool, though it lacks additional context that would make it more useful. The brevity is a positive, but it stops short of a fully structured explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters with good schema coverage, but no output schema and no annotations. The description does not explain the subscription lifecycle, how events are delivered, or what happens after creation. This is insufficient for an agent to fully understand the tool's role within the broader API context, especially given sibling tools for managing subscriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters having descriptions ('Event type to subscribe to' and 'Document ID'). The description adds no additional semantic nuance beyond the schema, but it doesn't need to since the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Subscribe to document events' uses a specific verb ('subscribe') and resource ('document events'), clearly indicating the creation of a subscription. It is distinct from sibling tools like subscriptions_info and subscriptions_delete, though the distinction is carried more by the tool name than the description itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or what conditions must be met (e.g., existing document). The description only states what it does, not the context for its use or how it relates to other subscription tools like subscriptions_info or subscriptions_delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavioral traits, but it only repeats the action. It does not state whether the deletion is permanent, if it requires special permissions, or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words. It is appropriately concise for a straightforward delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple with only one parameter, it is a destructive action with no annotations and no output schema. The description does not address reversibility, return value, or side effects, leaving significant behavioral 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 already fully documents the single parameter 'id' with a description, giving 100% coverage. The description adds no extra meaning for the parameter, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('a subscription'), making its primary purpose unambiguous. It distinguishes itself from sibling delete tools by naming the subscription resource, though it lacks any additional detail about scope or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no information about when to use this tool versus alternatives such as subscriptions_create or subscriptions_info. There are no stated prerequisites, exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, but it only states 'Get subscription information' without disclosing that this is a read-only operation, what data is returned, or any required permissions. This is insufficient transparency for a tool with no structured annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, with no redundant text. However, its brevity leaves out important context, so while it's well-structured, it's not as complete as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has simple parameters and no output schema, but the description doesn't explain what subscription information is returned or the meaning of 'subscription' in this context. The ambiguity is compounded by siblings like subscriptions_create/delete, and without annotations or output schema, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters ('Event type' and 'Document ID') at 100% coverage, so the baseline is 3. The description adds no additional meaning about parameter semantics, and the schema descriptions are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 subscription information' clearly identifies the verb (get) and resource (subscription information), distinguishing it from subscription creation/deletion siblings. However, it doesn't specify the scope (e.g., document/event) or what information is returned, relying on the input schema for those details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives. It doesn't mention that it's for viewing existing subscriptions, nor does it reference the sibling create/delete tools or any specific use case.
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?
There are no annotations, so the description must carry the full burden. It only says 'List', which implies a read-only operation, but it does not disclose side effects, authentication requirements, rate limits, or how the optional 'group' parameter affects behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no redundant words. It is appropriately sized for a simple list operation, efficiently conveying the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but there is no output schema, and the description does not explain what the returned list contains, how the optional 'group' parameter scopes the results, or how 'Telegram commands' are defined. This leaves the agent with incomplete information for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter 'group' with its description 'Telegram group'. The tool description adds no further meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('available Telegram commands'), making its core purpose unambiguous. However, it does not differentiate from sibling tools like 'loop_commands', which may also list commands in a different channel 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 such as 'loop_commands' or 'telegram_post'. The description does not state any context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only says 'invite', which implies creation but does not disclose whether an email is sent, whether the user is active by default, what permissions are required, or what the return value is. This is a significant transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler words. It is front-loaded and easy to parse, earning a high score for conciseness despite being minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema, no annotations), the description is too sparse to be complete. It fails to explain the invitation workflow, likely side effects (e.g., email notifications), or response format, which are crucial 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions (email, name, role), achieving 100% schema description coverage. The tool description adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Invite a new user to the workspace' clearly identifies the action (invite) and the resource (new user), distinguishing it from sibling tools like users_update or groups_add_user. It could be more direct by saying 'create' instead of 'invite', but it is not ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool over alternatives, any prerequisites, or context such as admin permissions. It simply states the function.
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 available, the description must carry the full behavioral disclosure burden. 'Delete a user account' implies a destructive action but does not mention irreversibility, cascading effects on user data, or required permissions. The agent is left without critical cautionary context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, and it is front-loaded with the main verb. However, it is so terse that it provides little beyond the tool name, slightly limiting its overall effectiveness despite being concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, this description is under-specified. It omits permanent effects, potential impacts on related resources, authorization needs, and any guidance about when deletion is appropriate versus suspension. The context is insufficient for an agent to safely invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'id' ('User ID to delete'). The tool description adds no additional parameter semantics beyond that schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a verb ('Delete') and resource ('user account'), which is unambiguous. However, it does not explicitly distinguish itself from sibling tools such as users_suspend or users_activate that also act on user accounts, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool as opposed to alternatives like users_suspend or users_activate. The description gives no context about prerequisites, appropriateness, or consequences, so the agent receives no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Get detailed information about a user,' which implies a read operation but gives no insight into return format, error handling, permissions, or side effects. There is nothing beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no unnecessary words. It is concise and appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is too sparse. It does not explain what 'detailed information' includes, whether any permissions are required, or what happens if the user does not exist. For a read-only tool, it could still benefit from specifying return fields or 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?
The input schema has a single parameter 'id' with a description 'User ID' and 100% coverage, so the baseline is 3. The description does not add any additional meaning about the id parameter, such as format, examples, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource 'detailed information about a user.' It is distinct from sibling tools like users_list (list all users) and users_update (modify). However, it does not explicitly state that it retrieves a single user by ID, though the schema covers that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 users_info is for retrieving a specific user while users_list is for listing all users, nor does it mention any exclusions or prerequisites. This is a minimal description with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'List workspace members,' implying a read operation, but does not disclose pagination behavior, sorting, filtering semantics, or whether any specific permissions are needed. This is insufficient for a tool with 7 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It is front-loaded with the essential purpose at the beginning. There is nothing irrelevant or redundant, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters (sort, limit, query, filter, offset, nextPath, direction) and no output schema, the description is too sparse. It does not explain how pagination works, what 'filter' or 'query' mean in practice, or how it relates to users_info. The description leaves significant gaps for a complex 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 parameters themselves are documented. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List workspace members' clearly states the verb and resource. It is unambiguous but does not explicitly differentiate from sibling tools like users_info or groups_list, so it's clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions. The description offers no context for choosing this over users_info or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 'list view statistics' without mentioning pagination, return format, read-only nature, or any side effects, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and annotations, so the description must explain return values and behavior. It does not mention what 'view statistics' includes, whether results are paginated, or how the limit/offset parameters affect output, making it incomplete 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 description coverage is 100%, so the schema already documents all parameters. The description adds no extra parameter semantics, but the baseline 3 applies because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists view statistics for a document, using a specific verb and resource. However, it doesn't differentiate from siblings like views_create or documents_viewed, so it lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as documents_viewed or views_create. The description gives no context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must disclose behavioral traits. It does not mention idempotency, error handling, permissions, or effects when the document is not currently starred. The description merely restates the action implied by the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is immediately front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is too minimal. It omits any behavior around already-unstarred documents, return values, or side effects. A simple tool still benefits from clarifying idempotency 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?
Schema description coverage is 100% (the only parameter 'id' is described as 'Document ID'). The description adds no additional parameter detail, but the baseline of 3 applies due to 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 a specific action: 'Remove star from a document.' It identifies the verb (remove), resource (star), and target (document), which unambiguously distinguishes it from sibling tools like documents_star (which adds a star) or documents_pin/unpin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 instead of alternatives such as stars_delete or documents_star. The description gives no context for selection among similar document operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Delete a group' without indicating whether deletion is permanent, requires special permissions, or impacts group memberships. For a destructive operation, this is critically insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no wasted words. It is front-loaded and gets straight to the point, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is not complete enough. It omits important context about deletion consequences, return values, and potential side effects. Even for a simple one-parameter tool, more information is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes one parameter 'id' with the description 'Group ID', achieving 100% schema description coverage. The description itself adds no extra meaning about the parameter, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a group' clearly identifies the action (delete) and the resource (group), making it specific and unambiguous. It distinguishes itself from sibling tools like groups_update, groups_remove_user, and groups_create, which perform different operations on groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when deletion is appropriate, any prerequisites, or that groups_remove_user might be used for removing a user instead. There are no exclusions or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It only states the action without disclosing idempotency, authentication requirements, or behavior when both or neither ID is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero filler, front-loaded verb. 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?
For a 2-param mutation with no output schema and no annotations, the description omits critical details: whether at least one ID is required, what happens if both are provided, and what the response looks like. It is minimally viable 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 coverage is 100% with descriptions for both parameters. The description adds no further semantic detail beyond what the schema already 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 action ('add') and the target resource ('document or collection') to favorites, distinguishing it from related tools like stars_list and stars_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no explicit guidance on when to use this tool versus alternatives like documents_star, nor any exclusions or prerequisites. The context is implied by the action but not stated.
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 behavioral disclosure. It only says 'Get redirect URL,' which implies a read operation, but does not explain what the redirect URL is used for, whether it expires, or if any authentication or permissions are needed. This is insufficient for a tool that might have side effects or access controls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It front-loads the action and resource, making it very concise and 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?
The tool is simple (one parameter, no output schema), so a minimal description might be acceptable. However, the return value is not specified beyond 'redirect URL,' leaving ambiguity about the format or behavior. Given the simplicity, this is a minimum viable description, but it could benefit from noting that the URL likely points directly to the attachment content.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the one parameter (id) with a description 'Attachment ID,' so schema coverage is 100%. The description itself adds no additional meaning beyond the schema, which is the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Get redirect URL for an attachment.' It uses a specific verb ('Get') and resource ('redirect URL for an attachment'), which distinguishes it from siblings like attachments_list or attachments_delete. However, it doesn't clarify how it differs from file_operations_redirect, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or comparison with similar tools like file_operations_redirect. This leaves the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'execute' and 'multiple changes' without disclosing atomicity, rollback behavior, error handling, or permission requirements—critical for a transaction tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no redundant wording, front-loading the verb and object. It is perfectly concise, though it sacrifices specificity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutating operation like a database transaction, the description is incomplete. It lacks information about atomicity, rollback, change structure, and expected outcomes, and the schema does not compensate with item definitions or an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for the single parameter 'changes' ('Array of changes to apply'), giving 100% coverage. The description adds no extra semantics such as the structure of each change, item format, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 (execute) and resource (database transaction), which distinguishes it from sibling tools like database_rows_list by implying a write operation. However, 'multiple changes' is vague and doesn't specify what kinds of changes are supported.
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 name and description imply this tool is for transactional operations, but there is no explicit guidance on when to use it versus alternatives or when not to use it. No mention of batching vs. individual calls 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?
With no annotations present, the description fails to disclose behavioral traits such as persistence, permissions required, or result of the operation. It only repeats the basic action without details on side effects or response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, immediately front-loading the action and format. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering 7 parameters, no output schema, and no annotations, the description is too sparse. It omits mention of required collectionId, optional flags like publish/template, and nesting via parentDocumentId, leaving the agent without enough context to select or invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters at 100% coverage. The description adds no new parameter semantics; the phrase 'Provide title and text in Markdown' is redundant with the schema and misleads by implying text is required, though it is optional (only title and collectionId are required).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Create') and resource ('a new document'), and additionally specifies content format ('text in Markdown'). This distinguishes it from update/delete/import operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as documents_update, documents_import, or documents_copy. The description doesn't mention exclusions, prerequisites, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of behavioral disclosure. It does not mention response format, error handling, authentication requirements, or any side effects. It only supplies the retrieval verb, offering no insight into what happens on failure or whether the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words or filler. It is appropriately sized for the tool's simplicity and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter) and no output schema or annotations, the description is minimal but not severely incomplete. It does not explain the return value or error behavior, but the action is straightforward and likely returns a revision object. It is adequate for a basic retrieval tool but could benefit from clarifying the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'id' with a description 'Revision ID' (100% coverage). The description adds no additional meaning beyond what the schema provides, so it remains at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('a specific document revision/snapshot'). It is specific and implies a single item by ID. However, it does not explicitly distinguish itself from sibling tools like revisions_list, though the word 'specific' hints at returning one revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as revisions_list or documents_info. The description only states what it does, leaving the agent to infer the appropriate context from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing return format, pagination, read-only nature, or auth requirements—expected for a list operation but still lacking detail.
Agents need to know what a tool does to the world before 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. It is appropriately minimal for the tool's simplicity.
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 param and no output schema, but the description fails to clarify what an 'insert' is or what the response looks like. It is minimally viable but leaves gaps for a caller.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter (syncBlockId) with 100% coverage. The description adds no extra meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('inserts of a sync block'), making the tool's function clear. It is distinct from siblings like sync_blocks_list (which lists blocks themselves), though it does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives, nor any exclusions or prerequisites. Usage is only implied by the name and minimal description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. 'Create an attachment upload URL' implies a side effect (creating a URL) but does not explain whether the file is actually uploaded, what permissions are required, or what the response contains. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundancy. It immediately states the core action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, and the description is only five words. It lacks information about the upload flow, response format, or relationship to other attachment operations, leaving the agent without enough context to use it effectively. Complexity is low, but the description is too sparse to be considered 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 clear descriptions for all four parameters (name, size, documentId, contentType). The description itself adds no extra semantic value beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Create') and the resource ('attachment upload URL'). It distinguishes itself from sibling tools like attachments_list, attachments_delete, and attachments_redirect, which are all different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, such as needing an existing document, or when it is appropriate to call this instead of documents_create or other attachment tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'get,' implying a read operation. It does not disclose what the configuration contains, whether any authorization is needed, or whether the operation is side-effect free. The single verb provides minimal behavioral context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is both succinct and directly informative. Every word contributes to the meaning, with no redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple getter with no parameters and no output schema, the description is minimally adequate. It tells the user that this tool fetches authentication configuration, but it does not specify the structure or content of the returned configuration, which could be useful given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty with 100% coverage. Since there are no parameters to explain, the description is not required to add parameter details. The baseline score of 4 applies here due to the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's main action: 'Get authentication configuration for the workspace.' It uses a specific verb ('get') and a clear resource ('authentication configuration'). However, it does not explicitly distinguish itself from the sibling tool auth_info, which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like auth_info. There is no mention of prerequisites, contexts, or exclusions, leaving the reader without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action ('create'), but does not explain side effects, required permissions, potential errors on duplicate names, or what the response contains. The behavior is largely opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no fluff. It is appropriately concise for a simple create operation, though it sacrifices behavioral detail that is covered elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 four parameters and no output schema, the description provides minimal context. It does not explain what happens upon successful creation (e.g., whether an object is returned), nor does it cover any edge cases or usage constraints. The tool is under-specified for an agent to understand the full operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all four parameters (name, color, private, description), so the schema already conveys param semantics. The description adds no additional meaning, but the baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new collection' uses a specific verb and resource, clearly indicating the operation. It distinguishes from sibling tools like collections_update and collections_delete because it is specifically the create action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, such as whether the user must be authenticated or whether a collection name must be unique, nor does it point to related tools like collections_update.
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 implications. It only says 'Delete a comment' without stating that deletion is likely permanent, requires appropriate permissions, or what side effects occur. This leaves the agent unprepared for the destructive nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that directly states the purpose with no wasted words. It is appropriately sized for a trivial operation and front-loads the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is too minimal. It fails to mention irreversibility, permissions, or what happens on success or failure, leaving the agent without essential contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter (id) with description 'Comment ID', so schema coverage is 100%. The description adds no additional meaning beyond the schema, aligning with the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a comment' clearly states the verb and resource, making it unambiguous and easy to distinguish from sibling tools like comments_update or comments_resolve. The single action is fully described without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or situations where deletion is appropriate, leaving the agent without explicit 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, the description carries the full burden of behavioral disclosure, but it only states the basic action. It does not reveal whether the copy is a deep copy, whether permissions or sharing settings are preserved, if the operation is reversible, or what the return value is. This lack of detail is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise: a single sentence that front-loads the core purpose. It contains no filler or redundant information, earning full marks for brevity and clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and no annotations, the description is insufficiently complete. It does not mention that the optional parameters allow the copy to be placed in a different collection or under a parent document, nor does it hint at the response format. A copy operation typically has side effects (creating a new document) that should be disclosed for the agent to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters (100% coverage) with descriptions for id, collectionId, and parentDocumentId. The description adds no additional meaning beyond the schema, but since the baseline is 3 for high schema coverage, this score is appropriate. The tool description does not clarify relationships between parameters or default behaviors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'copy' with the resource 'document', clearly indicating the operation. It distinguishes itself from siblings like documents_create, documents_move, and documents_restore, as no other tool explicitly mentions 'copy'. The one-sentence description directly states the tool's purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as documents_create for creating a new document or documents_move for relocating one. There are no explicit usage conditions, prerequisites, or exclusions, leaving the agent without contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that a document is imported from a file, but does not mention side effects (e.g., whether a new document is created, if it can be published), permissions needed, or error behavior. The minimal wording provides little beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and to the point, making it highly efficient. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is seriously under-specified. It fails to explain return values, use cases, or behavioral nuances. For a tool of this complexity, more context is needed to guide an AI agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all five parameters. The description adds no additional meaning about parameters, but since the schema fully covers them, the baseline 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 ('Import') and the resource ('a document') and specifies the input source ('from a file'). This distinguishes it from siblings like documents_export (which goes to a file) and documents_create (which doesn't specify a file source). However, it doesn't provide details about the import process or output, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (importing a document from a file) but provides no explicit guidance on when to use this tool versus alternatives like documents_create or documents_update. There is no mention of exclusions or prerequisites, so it falls at 'implied usage' rather than clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, so the description carries the full burden. It only states that it searches across all documents but does not disclose default exclusions (e.g., drafts/archived), permissions required, or output behavior. This is insufficient for a search tool with multiple filter params.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no redundancy, making it concise and easy to parse. However, its brevity sacrifices informational depth, but for this dimension, it earns a high score for clarity and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and no output schema, the description is too thin. It fails to mention the result format, pagination behavior, or how filters like includeDrafts and includeArchived affect the search. This leaves the agent without enough context to correctly invoke the tool in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all 9 parameters with descriptions, so baseline is 3. The description itself adds no parameter-specific detail; it only clarifies the overall search scope, which does not enhance understanding of individual params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and 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 this as a full-text search tool targeting all documents, with a specific verb (search) and resource (all documents). It distinguishes from the sibling 'documents_search_titles' by implying it searches content, not just titles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents 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 usage guidance is provided; the description does not mention alternatives like documents_search_titles or when to use this instead of documents_list. The context is only implied by the tool name and the phrase 'full-text'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'List starred documents' and does not reveal pagination behavior, sorting semantics, authentication requirements, or whether it returns metadata or full content. It does not contradict any annotations but is insufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is concise and appropriately sized for a simple list operation, with the key verb and resource front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 optional parameters, no output schema, and no annotations, the description is too sparse. It does not explain the effect of parameters, clarify whether 'starred documents' means the current user's stars or all starred items, or describe the response format. Additional context about pagination and sorting would be necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions, so the baseline is 3. The tool description adds no parameter semantics beyond the schema, and the schema descriptions are minimal but present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'starred documents', clearly distinguishing it from sibling tools like documents_list (all documents) and documents_viewed (viewed documents). It directly conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as documents_list or documents_search. There is no mention of exclusions or preferred contexts, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 simply states the action without disclosing behavioral details like pagination behavior, sorting options, whether authentication is required, or how 'recently viewed' is defined. The schema hints at pagination and sorting, but the description adds no transparency about these behaviors, making it a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly communicates the tool's purpose with zero wasted words. It is appropriately concise for a simple list operation and earns full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple description, the tool has five parameters (including pagination) and no output schema. The description does not explain the return format, the meaning of 'viewed', or how pagination works. With no annotations to supplement, the agent lacks crucial context about expected behavior and result structure, making this incomplete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters (sort, limit, offset, nextPath, direction), so the schema already documents them. The description adds no extra parameter semantics. As per the baseline for full schema coverage, a score of 3 is appropriate; the description does not compensate with additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List recently viewed documents' clearly states the verb (list) and resource (documents) with a specific scope (recently viewed). It distinguishes from sibling tools like documents_list and documents_search by focusing on the 'viewed' history. However, it does not explicitly clarify whether these are the current user's viewed documents or system-wide, nor does it mention an alternative tool, so it falls short of the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as documents_list, documents_search, or documents_starred. The usage is implied by the name and description (use when you need recently viewed documents), but there are no exclusions or comparison with sibling tools, so it earns a middle score.
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 carries the full burden for behavioral disclosure. It only says 'List', implying read-only, but provides no details about pagination, filtering, permissions, or response format. Minimal value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently states the core function without wasted words. It is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 10 parameters and no output schema, the description does not explain return values, filter semantics, or behavioral nuances. It is too sparse to fully guide an agent, especially given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters. The description adds no parameter information, but the schema already documents all 10 parameters, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'workspace events' and clarifies with '(audit log)', making it distinct from sibling list tools. It immediately conveys the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like documents_list or audit-specific tools. It lacks context about typical use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral disclosure. It only says 'create' with no details about side effects, required permissions, idempotency, or whether this activates the provider immediately. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the tool's purpose with no extraneous words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters (7 required), no annotations, and no output schema, the description is too sparse. It does not explain what the tool returns (e.g., provider ID), mention prerequisites like existing configuration, or address edge cases such as duplicate providers. The minimal description leaves too much unstated for a complex 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?
The schema descriptions cover 100% of the 9 parameters, so the baseline is 3. The description does not add any parameter context beyond what the schema already provides, but it also doesn't need to since the schema is fully documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create LDAP authentication provider' uses a specific verb (create) and resource (LDAP authentication provider), clearly distinguishing it from sibling tools like ldap_login (which performs authentication) and ldap_ping (which tests connectivity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 provider_enable or provider_info. There is no mention of prerequisites, when not to use it, or how it differs from related provider management 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?
With no annotations provided, the description carries full responsibility for disclosing behavior. It only states 'Delete' without mentioning permanence, irreversibility, or potential effects on authentication flows, which are critical for a deletion operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant information. It is efficient and front-loaded, exactly as expected for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits essential safety context such as irreversibility, potential impacts on existing sessions or integrations, and any required permissions. For a delete operation with no annotations or output schema, this is insufficient for an agent to assess risks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter 'type' with description 'Provider type', and the tool description adds no additional meaning. Since schema coverage is 100%, the baseline is 3; no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an authentication provider' with a specific verb and resource. It distinguishes itself from sibling tools like provider_enable and provider_info by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or consequences. The description is a bare statement with no contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure, but it only restates the tool name without adding any context about side effects, authentication requirements, or return format. 'Get' implies read-only, but this is not explicitly stated, and no additional behavioral details are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter info retrieval tool, the description is minimally viable, but the lack of distinction from sibling tools like auth_info and auth_config makes it incomplete in context. The agent cannot determine whether this tool is the right choice based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already fully covers this (100% coverage). The description does not need to explain parameters, so a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('authentication provider information'), so it is specific about the tool's function. However, it does not differentiate from sibling tools like auth_info or auth_config, which likely have overlapping purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. Given the existence of auth_info and auth_config in the sibling list, the absence of any context about selection criteria leaves the agent to guess.
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 behavioral disclosure. It only states that a password is created, but does not mention whether an existing password is overwritten, whether any authentication is required, or what the function returns. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the verb and resource. It contains no fluff and is appropriately sized for a simple tool with one parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must explain return values and side effects. It does not, leaving the behavior incomplete. The presence of only one parameter mitigates this somewhat, but the description remains insufficient for a mutation 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 single parameter shareId is fully described in the schema as 'Share ID', giving 100% schema coverage. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and a specific resource 'password for a share link', clearly distinguishing it from sibling tools like shares_create which create the share itself. This is a clear and unambiguous statement of the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as shares_update which might also modify share settings. There are no prerequisites explained (e.g., the share must already exist) or scenarios where this tool is preferred.
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 behavioral disclosure. It only states 'Delete an attachment,' which implies destructive action but does not mention permanence, permissions, side effects, or success/failure behavior. 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 a single, succinct sentence that directly states the action. There is no redundant information, and every word earns its place. It is well-front-loaded and appropriately sized for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no output schema), and the description is minimally viable. However, given the lack of annotations and the absence of any behavioral or usage details, the description is not fully complete for an agent to understand all implications, though it may suffice for a straightforward delete 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 schema already provides full coverage for the single parameter 'id' with its description 'Attachment ID.' The tool description adds no additional meaning or context about the parameter, 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 'Delete an attachment' uses a specific verb (delete) and resource (attachment), clearly distinguishing it from sibling tools like attachments_list, attachments_create, and attachments_redirect. It unambiguously states the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as prerequisites (e.g., needing an existing attachment ID) or scenarios where deletion is appropriate. There are no exclusions or alternatives mentioned, leaving the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states the action; does not disclose idempotency, permission requirements, or behavior if group already has access.
Agents need to know what a tool does to the world before 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.
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?
Simple tool with two fully-described parameters and no output schema. Description conveys the core action, but lacks behavioral detail such as idempotency or permission requirements, which would be expected given 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 covers both parameters with descriptions (Collection ID, Group ID) at 100% coverage. 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 uses specific verb 'Grant' and identifies both resources: group and collection. Clearly distinguishes from sibling tools like collections_add_user (user vs group) and collections_remove_group (add vs remove).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 collections_add_user or groups_add_user. Does not mention that it's for group-level access only 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?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action without revealing side effects, idempotency, permission requirements, or behavior when the user already has access. This is a mutation tool, and the description is silent on those aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the essential action with no filler. Every word contributes meaning, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter operation, the description is minimally adequate, but with no output schema and no annotations, it leaves out any error handling, return behavior, or edge-case context. It is complete enough for a basic understanding but lacks depth for an agent to anticipate failures or side 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?
The schema already documents both parameters (id as Collection ID, userId as User ID) with 100% coverage. The description adds no further meaning beyond matching the resource and user, so it meets the baseline without enriching 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?
The description 'Grant a user access to a collection' uses a specific verb ('grant') and resource ('collection'), clearly distinguishing it from sibling tools like collections_add_group (which grants a group) and collections_remove_user (which revokes access). It is unambiguous and action-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like collections_add_group or any prerequisites (e.g., user/collection existence). Usage context is only implied by the tool name and sibling list.
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 carries the full burden of behavioral disclosure, but it only states the action without explaining output format, side effects, permissions, or any potential limitations (e.g., performance impact). This is a minimal statement of intent, not a transparency disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is easy to parse and front-loads the key action. It contains no waste, though it could benefit from slightly more context while still remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of zero parameters, the description is still incomplete because it does not specify what the export output looks like (e.g., file format, collection data structure) or any constraints (e.g., whether all collections includes trashed ones). The lack of an output schema and annotations amplifies this gap, making it difficult for an agent to know how to handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides full coverage (100%) by default. The description does not need to explain any parameter semantics, earning a baseline of 4. No additional compensation 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 'Export all collections' uses a specific verb ('export') and identifies the resource ('collections') with an explicit scope ('all'). This distinguishes it from the sibling tool 'collections_export', which likely handles individual collections, though it does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or cases where a different tool should be chosen, 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?
No annotations are provided, so the description must carry the full burden. 'List' implies a read-only operation, but the description does not disclose pagination behavior, filtering capabilities, or any other operational details beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded and contains no extraneous words. It communicates the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is adequate but has gaps: no mention of pagination or filtering, and ambiguity with similar sibling tools is not addressed. The schema is rich, but the description alone is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 five parameters described. The description adds no parameter semantics beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the resource ('group memberships of a collection'). It clearly distinguishes from sibling tools like collections_memberships (likely user memberships) and groups_memberships (members of a group).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as collections_memberships or groups_memberships. The context is clear but there is no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral disclosure. It only states that the tool updates an existing comment, but does not disclose what happens if the comment does not exist, whether authentication is required, how the update affects other fields, or what the response contains. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the action. It is front-loaded and contains no filler or redundant information. Every word contributes to understanding the tool's 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?
Given the simplicity of the tool (2 parameters, both required and well-documented), the description is minimally viable but lacks context about failure modes, permissions, or return values. There is no output schema and no annotations, so the description could do more to explain behavior, though the tool is simple enough that this is a clear gap but not severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for both parameters ('Comment ID' and 'Updated comment text in Markdown'). The description adds no additional parameter semantics, but given the high schema coverage, the baseline of 3 is appropriate. The tool's description does not need to repeat schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing comment' uses a specific verb ('Update') and resource ('existing comment'), clearly distinguishing it from sibling tools like comments_create, comments_delete, and comments_list. It precisely conveys the tool's core function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is the appropriate tool for modifying comment text specifically, nor does it exclude cases like resolving or deleting comments. No explicit alternatives or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only restates the list operation and does not disclose permissions, pagination, ordering, or response format. 'List' implies read-only, but additional behavioral context is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word is meaningful and the structure is optimal for quick parsing.
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, but with no output schema, the description should hint at return values or behavior. It doesn't, leaving some ambiguity. However, the name and schema make basic invocation clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (collectionId) with a clear description. The tool description adds no extra semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List') and resource ('pinned documents in a collection'), clearly distinguishing it from siblings like documents_list and documents_starred. The scope is precise 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 choose this tool over alternatives such as documents_list or documents_starred. There are no prerequisites, exclusions, or contextual tips.
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 carries the full burden. It states the status change but does not disclose any side effects, such as loss of public access, reversibility, permissions required, or impact on existing links. This absence of behavioral context leaves the agent with an incomplete picture of the operation's consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of nine words, front-loaded with the action. Every word contributes meaning, with no fluff or redundancy. It is an excellent example of minimalist specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one required parameter) and clear purpose, the description is minimally viable. However, it lacks behavioral transparency and usage guidance, which are important for a mutation tool without annotations or output schema. It is adequate for a trivial operation but leaves gaps in non-obvious aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has one parameter 'id' with description 'Document ID', giving 100% schema coverage. The description adds no additional meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Move') and resource ('a published document') with a clear target state ('back to draft status'). It is distinct from sibling tools like documents_delete, documents_archive, and documents_restore, making the tool's function unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 typical scenarios (e.g., rolling back an accidental publish) or contrast with related operations like archive or delete. The usage context is only implied by the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action, not error conditions, idempotency, permissions, or response behavior. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero redundancy. Perfectly concise and front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The simple action and complete schema make the description minimally viable, but it lacks context about expected outcomes or prerequisites. Given no annotations, more detail would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (Group ID and User ID) with descriptions, so the description adds no extra meaning. Baseline 3 applies since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a user to a group, using a specific verb and resource. It distinguishes from siblings like groups_remove_user and groups_memberships, which have different actions on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions. The description simply states the action, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It implies a read operation ('Get') but does not explicitly state that it is non-destructive, whether special permissions are required, or what the response contains. The bare phrase 'detailed information' is vague and does not set expectations for side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words or repetition. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but the description lacks specifics about the return value. 'Detailed information' is ambiguous and does not enumerate what fields are included or whether the response is the full group object. While minimal, it is not misleading, but it leaves the agent guessing 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?
The input schema fully documents the only parameter 'id' as 'Group ID', achieving 100% schema coverage. The description adds no additional meaning beyond the schema, so it meets the baseline without 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?
The description 'Get detailed information about a group' clearly states the action (get) and the resource (group). It is specific enough to distinguish from sibling tools like groups_list, which lists groups, and groups_update, which modifies a group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing a valid group ID, or contrast with related tools like groups_memberships or groups_list. No context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It states 'List members' but does not mention pagination behavior (though hinted by limit/offset/nextPath params), authorization requirements, or whether the operation is read-only. Minimal behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets straight to the point with no superfluous words. It is perfectly sized for the simple 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 is relatively simple with only one required parameter, but it has multiple optional parameters for pagination and filtering. The description does not explain how these interact (e.g., nextPath vs offset) or what the return format is, yet the full schema coverage compensates to some degree. Adequate but lacking depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 covers 100% of parameters with descriptions, so the baseline of 3 applies. The description adds no extra meaning beyond the schema, but the schema itself is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'members of a group', clearly distinguishing this from sibling tools like groups_add_user or groups_remove_user. It immediately conveys the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as groups_info or groups_list. The description is purely functional and offers no exclusions or alternative tool references.
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 carry the full disclosure burden. It only states the action without mentioning side effects, permission requirements, reversibility, or the impact on existing provider configuration. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant words. It is appropriately sized for the tool's simplicity and immediately states the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter tool with a fully documented schema, so the description is minimally viable. However, it omits important context such as the effect of setting isActive, acceptable 'type' values, or whether the operation is admin-only. It is adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters already described ('Provider type' and 'Whether provider is active'). The description adds no additional parameter context, 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 'Enable or disable an authentication provider' uses a specific verb pair and identifies the resource ('authentication provider'), clearly distinguishing it from sibling tools like provider_delete and provider_info. Even though the tool name suggests only 'enable', the description accurately captures both enable and disable behaviors via the isActive flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as provider_delete or provider_info. It does not state prerequisites, exclusions, or provide any decision framework, leaving the agent without context on selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says only 'Revoke a public share link' without disclosing any behavioral traits such as irreversibility, required permissions, or side effects. With no annotations available, this leaves the agent without critical safety information for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that wastes no words. It effectively communicates the core action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description is near-minimal but adequate. However, it lacks any usage context or caution about the destructive nature of revocation, 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?
Schema description coverage is 100% (the 'id' parameter is described as 'Share ID to revoke'), so the baseline is 3. The tool description adds no further parameter context, but the schema already suffices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Revoke') and the resource ('public share link'), distinguishing it from sibling tools like shares_create and shares_update. 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 such as shares_update or shares_delete. The description lacks context about suitable scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no information about side effects, permanence, or error behavior. It only says 'Remove an item from favorites' without disclosing whether the removal is reversible or what happens on invalid IDs.
Agents need to know what a tool does to the world before 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, straightforward sentence with no unnecessary words, making it highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For such a simple tool with one parameter and no output schema, the description is adequate but minimal. It lacks explanation of what 'favorites' means in the system or any context on authorization, but the simplicity of the operation partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the 'id' parameter with the description 'Star ID to remove', providing 100% coverage. The tool description adds no additional meaning about the parameter, so it remains at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and the resource ('favorites'), and the tool name 'stars_delete' confirms the scope. It distinguishes from siblings like stars_create and stars_list by implying the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as documents_unstar or when not to use it. The description only states the action, leaving it to the agent to infer appropriate usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry full burden for behavioral disclosure. It states the action but does not disclose side effects (e.g., that it sends a live message to Telegram), whether it is idempotent, or what happens if the collection has no updates. The verb 'post' implies an external write but lacks explicit transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, six words long, front-loaded with the action. No filler or redundancy. It is concise and appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema or annotations, the description is minimal but covers the core function. However, it lacks usage context (e.g., when to post an update) and does not explain what constitutes an 'update' or how the result is returned. This is sufficient for basic understanding but not fully 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 for collectionId with its description 'Collection ID'. The tool description adds no additional meaning beyond the schema, so baseline 3 applies. There is no extra context about how to obtain or format the collection ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Post a collection update to Telegram' uses a specific verb ('post') and resource ('collection update') with a clear destination (Telegram). It distinguishes from siblings like telegram_commands and loop_post by indicating a specific action on a collection for a Telegram channel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not specify prerequisites, use cases, or exclusions. Sibling tools like telegram_commands or loop_post exist, but no comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It does not mention side effects (e.g., whether the user loses all admin privileges, if it is reversible, or any restrictions such as demoting the last admin). This is a significant gap for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It is appropriately sized for a simple one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description states the core purpose, but lacks behavioral context such as side effects or usage prerequisites. While it is minimal, it is not entirely inadequate for a straightforward action, hence a 3.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 the parameter 'id' described as 'User ID to demote'. The tool description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Demote a user from admin' uses a specific verb ('demote'), identifies the resource ('user'), and specifies the scope ('from admin'). It clearly distinguishes from the sibling tool 'users_promote' which performs the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like users_promote or users_suspend. It does not state that users_promote should be used to grant admin privileges or any prerequisites for demotion.
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. However, it only states the action without disclosing any side effects, permission requirements, reversibility, or return behavior. The agent is left guessing about the consequences of promotion.
Agents need to know what a tool does to the world before 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 zero waste. It is front-loaded and efficient, conveying the core action without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is adequate for basic understanding but lacks contextual details such as when to use it, any side effects, or what the response contains. It is minimally complete but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter 'id' with the description 'User ID to promote'. The tool description adds no additional meaning beyond what the schema already states, 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 uses a specific verb 'Promote' with a clear resource 'user' and target 'admin', making the tool's purpose immediately understandable. It also distinguishes itself from sibling tools like users_demote and users_activate by stating the exact action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as users_demote or users_update. There are no prerequisites, context, or exclusions 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?
With no annotations, the description carries full responsibility for behavioral disclosure. It only says 'Suspend (disable)' without revealing side effects such as whether the user loses access immediately, whether it is reversible, or what happens to sessions and data. The description adds no context beyond the tool name's literal meaning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is front-loaded with the verb and resource, making it immediately readable 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?
For a simple tool with one parameter and no output schema, the description conveys the essential action. However, it omits important context such as verification on whether the account can be reactivated, or any side effects a user might face. The presence of users_activate in sibling tools suggests that noting reversibility would complete the picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%: the single parameter 'id' is already described as 'User ID to suspend'. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Suspend') and the resource ('a user account'), with a parenthetical clarification ('disable') that adds precision. It distinguishes from sibling tools like users_delete (permanent removal) and users_activate (opposite action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use suspend versus alternatives like users_delete or groups_remove_user. The description implies a disabling action but does not state prerequisites, reversibility, or scenarios where this tool is preferred. Given the availability of users_activate as a potential counterpart, explicit contrast would be valuable.
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 behavioral disclosure. It only says 'update,' which implies mutation, but does not mention permission requirements, effect immediacy, reversibility, or response format. This is a minimal disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the core purpose without padding, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema, no annotations), the description is minimally viable but lacks behavioral context expected for a mutation. However, the schema fully covers parameters, so the description does not need to compensate for schema gaps. It is adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (name, avatarUrl) having clear descriptions in the schema. The tool description adds no additional parameter semantics beyond saying 'profile,' so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update current user's profile.' uses a specific verb ('update') and resource ('current user's profile'), clearly distinguishing it from sibling tools like users_create, users_suspend, or users_delete. The scope is precisely defined as the current user, which eliminates ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions. It simply states the action without context like prerequisites, typical use cases, or comparisons to other user management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic action and scope, without disclosing pagination behavior (how 'all' is retrieved), any rate limits, or what the response contains. The schema hints at pagination via parameters, but the description does not explain the relationship.
Agents need to know what a tool does to the world before 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, front-loaded with the verb and resource. There is no unnecessary filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain what the list returns and how pagination works. It only provides a terse statement without covering these aspects, making it incomplete for a tool with pagination parameters and no 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%, with limit, offset, and nextPath all documented. The description adds no extra semantic meaning beyond the schema, so baseline 3 applies. It does not clarify how these parameters relate to 'all accessible collections', but the schema descriptions handle parameter basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all accessible collections' uses a specific verb (List) and resource (collections), clearly distinguishing it from sibling tools like collections_info or collections_documents. It defines the scope as 'accessible', which clarifies what will be returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to retrieve the set of collections the user can access, but provides no explicit guidance on when to choose this over alternatives. However, given the many list-type sibling tools, the intended pattern is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without detailing side effects, permissions, reversibility, or what happens if both collectionId and parentDocumentId are specified. The lack of ambiguity resolution leaves the agent with insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It front-loads the action and destination clearly, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description is too sparse to be fully complete. It does not describe the return value, error conditions, or any behavioral constraints, which is a significant gap for a mutation tool. The sibling tools span many document operations, adding pressure for more contextual detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters with 100% coverage. The description adds minimal context by clarifying the purpose of the target fields, but it does not explain whether the parameters are mutually exclusive, optional beyond id, or what format the IDs should take. This stays at the baseline for schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Move') and resource ('document'), and clearly specifies the destination ('different collection or parent'). This distinguishes it from sibling tools like documents_copy and documents_update, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of related tools. The intended usage is implied by the description itself, but it does not differentiate from similar operations like copying or updating a document's metadata.
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 behavioral disclosure. It only states the basic operation, leaving unclear whether restoration is reversible, requires permissions, overwrites existing documents, or affects permissions/metadata.
Agents need to know what a tool does to the world before 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 declarative sentence front-loaded with the verb and resource. It contains no filler and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is too sparse. It omits important operational details such as whether restoration targets the original location, any time limits, or the effect of revisionId. The complete schema does not fully compensate for this 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?
The input schema fully documents both parameters (id and revisionId) with descriptions, so the baseline is 3. The description adds context by specifying valid source states (archived/deleted), but does not explain the role of revisionId 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 identifies the action (restore) and the target (an archived or deleted document). It distinguishes from sibling tools like documents_archive and documents_delete by explicitly naming the states being reversed.
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 implies usage for archived or deleted documents, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. Given the presence of sibling archive/delete tools, more explicit guidance would be helpful.
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?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only says 'unpin' without mentioning side effects, permission requirements, failure conditions, idempotency, or the impact on the collection membership.
Agents need to know what a tool does to the world before 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, front-loaded with the action and resource, and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description adequately conveys the core operation. However, it lacks usage guidance and behavioral details, which prevents a top score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'id' parameter, described in the schema as 'Document ID'. The description adds no extra semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Unpin') and a clear resource ('document'), and adds scope ('from its collection'), distinguishing it from related tools like documents_unpublish and documents_pin. The action is immediately 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, when not to use it, or which alternatives might be more appropriate. It simply states the action, with no context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the basic purpose and does not explain what the output looks like, whether all attachments means global scope, or any potential side effects or permissions. This is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded with the action and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no annotations, the description is minimal but adequate. However, it lacks details such as the units of size (bytes, KB, etc.) and whether 'all attachments' is system-wide or scoped to a specific context. No output schema exists to clarify the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty, providing 100% schema coverage vacuously. The description does not need to add parameter details, and it correctly implies no filtering options. No additional param semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get total size of all attachments' clearly states the action (get), the resource (attachments), and the scope (total size of all). It distinguishes from siblings like attachments_list and attachments_delete by targeting aggregate size, not listing or mutating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. It does not state prerequisites, exclusions, or mention related tools such as attachments_list. The usage context is entirely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the action ('revoke a group's access') but does not disclose whether it is idempotent, what permissions are required, or what happens if the group does not have access. 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 a single sentence that conveys the core action without any fluff or repetition. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The operation is simple with only two parameters and no output schema. The description is adequate for a basic revoke action, but it does not provide context about prerequisites, side effects, or error behavior. A more complete description could mention that this only affects group access, not user access, and any permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters (id and groupId) with 100% coverage. The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'revoke' and clearly identifies the resource (group access) and target (collection). It distinguishes this tool from siblings like collections_add_group and collections_remove_user by focusing on group removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a group's access to a collection needs to be removed, but it does not explicitly state when to use this tool versus alternatives such as collections_remove_user or groups_remove_user. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only states the action without mentioning consequences, reversibility, authorization requirements, or impact on existing access paths—significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, perfectly concise for the tool's simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and parameters are well-documented, but the lack of annotations and any behavioral context (e.g., return value, idempotency, permissions) leaves the agent without full guidance for executing this mutation safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for both parameters ('Collection ID' and 'User ID') with 100% coverage, so the description adds no additional meaning beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Revoke') and the target ('a user's access to a collection'), making it distinct from sibling tools like collections_add_user or collections_remove_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to revoke a user's collection access) but provides no explicit guidance on when to prefer this tool over alternatives, such as collections_remove_group for groups, or any prerequisites or side conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the immediate visual effect and does not mention reversibility, required permissions, whether the document remains searchable/accessible, or any side effects. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently captures the action and outcome for a simple one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the basic operation is understandable. However, without annotations or any mention of reversibility/access side effects, the description is adequate but leaves meaningful gaps for an agent deciding between archive and related tools like delete or restore.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 full coverage: one required parameter 'id' with description 'Document ID'. The tool description adds no extra parameter meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Archive') with a clear resource ('a document') and an observable outcome ('hide it from the main view'). This distinguishes it from sibling tools like documents_delete, documents_restore, and documents_move, even without naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'hide it from the main view' implies a use case—decluttering the main view without permanently deleting—but there is no explicit guidance on when to use this tool versus delete, restore, or unpublish. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral disclosure. It states the document is moved to trash, implying non-destructive deletion, but does not mention any permissions required, whether the trash is recoverable, or what happens to the document after being trashed. No annotation contradicts the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the action. No wasted words, and the essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one well-documented parameter, the description is minimally adequate. However, with no annotations and no output schema, it does not clarify side effects (e.g., whether trash is reversible, retention policies) or distinguish itself from related tools. It is more complete than a tautology but still leaves 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 schema fully documents the single parameter 'id' as 'Document ID' (100% coverage), so the description adds no additional parameter meaning. The baseline of 3 applies because the schema already handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Move' and the resource 'document to trash', clearly distinguishing this delete operation from sibling tools like documents_move (which moves to a new location) and documents_archive (which archives without trashing). The action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the deletion tool by naming the trash destination, but it does not explicitly state when to use this versus alternatives like documents_archive or documents_move. It provides no exclusion criteria or alternative recommendations, though the phrase 'move to trash' implies a soft-delete behavior.
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 must carry the burden of behavioral disclosure. It only says 'Get detailed information' without specifying what 'detailed' includes (e.g., metadata, content, permissions), any authentication or permission requirements, or whether the operation is purely read-only. The description adds little beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core function. Every word is purposeful, with no redundant or filler content, making it highly scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with two parameters and no output schema. The description gives a clear purpose but does not explain what 'detailed information' comprises, nor does it mention any error behavior or return format. Given the lack of annotations and output schema, a slightly richer description would have been more complete, but the current description 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?
The schema already provides thorough descriptions for both parameters (id: 'Document UUID or urlId'; shareId: 'Share ID'), achieving 100% coverage. The description echoes 'by ID or share ID', reinforcing that these are alternative identifiers, but this is marginal added value over the schema. Therefore, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get detailed information about a document by ID or share ID.' It specifies the action (get), the resource (document), and the scope (by ID or share ID), and distinguishes it from siblings like documents_list and documents_search, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. Usage is implied by the name and description: for retrieving details on a single known document, as opposed to listing or searching. However, no exclusions or alternative tool references are provided, so it only meets the 'implied usage' bar.
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 behavioral disclosure burden. 'Revoke' implies a mutation, but there is no information about permission requirements, reversibility, side effects, or error conditions. The description adds no context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the operation. There is no fluff, and it is easy to parse. It earns a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description is functionally adequate, but it lacks behavioral and contextual details that would be useful in a broader workflow (e.g., whether the user must currently have access, or how to list current users). Given the absence of annotations and output schema, it is minimally complete but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage (both 'id' and 'userId' have descriptions), and the description does not add further meaning to the parameters. It correctly maps 'userId' to the user's access being revoked, but this is already in the schema. 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 'Revoke a user's access to a document' uses a specific verb ('revoke') and clearly identifies the resource (a user's access to a document). It is easily distinguishable from sibling tools like documents_add_user or documents_users, and is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case (removing a user's access) but does not explicitly state when to prefer this over alternatives, nor does it mention any prerequisites or exclusions. It serves as a clear context cue, but the guidance is minimal.
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?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only states the basic update action and does not reveal side effects, permission requirements, or the meaning of key flags like append, publish, and template. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It front-loads the verb and resource, and the list of fields is concise. It earns its place without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema's rich parameter descriptions and the tool's moderate complexity, the description is adequate but not thorough. It lacks usage guidance and behavioral context, and there is no output schema, so it is only partially complete for an agent deciding whether and how to invoke 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?
The schema provides 100% description coverage for all parameters, so the description does not need to add much. It mentions 'title, text' specifically but adds no extra meaning beyond what the schema already states, and 'other properties' is vague. The baseline of 3 is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Update') and resource ('existing document'), and mentions key fields ('title, text, or other properties'). This distinguishes it from sibling tools like documents_create or documents_delete, and the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the verb 'update' and the phrase 'existing document', but there is no explicit guidance on when to use this tool versus alternatives (e.g., documents_create for new documents). It provides no exclusions or alternative tool references.
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 bears the full burden of behavioral disclosure. It only says 'Get', which implies a read operation, but it omits any details about authentication requirements, behavior for invalid or incomplete operation IDs, or whether the redirect URL is temporary. This adds little beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, 'Get redirect URL for a file operation result,' which is concise and front-loaded, with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is very simple with one parameter and no output schema, so the description is minimally adequate. However, it lacks any context about the return value (e.g., the format of the redirect URL) or prerequisites (e.g., the operation must be completed), which would improve completeness given the absence of annotations and an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter with the description 'File operation ID', and the tool description does not add any additional meaning or context beyond what the schema already provides. Baseline 3 is appropriate when the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('redirect URL'), and the specific context ('for a file operation result'). This distinguishes it from sibling tools like attachments_redirect or file_operations_info, which focus on different resources or aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a file operation ID is available and a redirect URL is needed, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Usage context is inferred from the name rather than articulated.
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 must fully disclose behavioral traits, but it only states the basic action. It does not mention any side effects, permission requirements, uniqueness constraints, or what happens to the old name, leaving the agent without important operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly states the action, the resource, and the specific attribute being updated, achieving maximum conciseness while remaining unambiguous.
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 only two required parameters fully described in the schema. However, since there is no output schema and no annotations, the description could benefit from noting return behavior or side effects. The lack of such context makes it adequate but not complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for both parameters (id and name), so the schema already documents their meaning. The description adds no additional parameter semantics beyond what is already in the schema, which is the baseline 3 according to the rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a group's name' uses the specific verb 'Update' with a clear resource ('group') and the specific field being changed ('name'). This distinguishes it from sibling tools like groups_create, groups_delete, and groups_info, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage but provides no explicit guidance on when to use this tool versus alternatives, prerequisites, or exclusions. The narrow scope ('update a group's name') makes usage self-evident, but it lacks the explicit alternative/context statements seen in higher-quality descriptions.
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 carries the full burden of behavioral transparency, but it only restates the action. It does not disclose output format, pagination, permissions, or error behavior. This provides minimal extra value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no fluff. It is appropriately sized and front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool, the description is adequate but incomplete. No output schema or annotations exist, so the description should explain what is returned (e.g., channel IDs, names, metadata) or any prerequisites. It leaves these details ambiguous 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 schema has 100% coverage for teamId, so the baseline is 3. The description adds no meaningful parameter semantics; it only refers to a 'Loop team' without clarifying what a team ID is or how to obtain it. The parameter meaning is still underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (list) and resource (channels), scoped to a Loop team. This clearly distinguishes it from sibling tools like loop_teams, which lists teams, and other loop_* tools that perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (list channels when you need them for a team) but gives no explicit guidance on when to use this tool versus alternatives, and no mention of prerequisites like obtaining a teamId from loop_teams. Lacks exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It states that the share is public, but does not mention write implications, authentication requirements, side effects (e.g., whether an existing share is replaced), or return value. Minimal behavioral detail beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the action and resource. No filler or redundant information. Perfectly sized for the tool's simplicity.
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 one-parameter tool, the description is adequate but incomplete. It does not mention the return value (e.g., the share link or share ID), which is relevant since there is no output schema. It also lacks any context about prerequisites or behavior if a share already exists. This makes it minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the required parameter. The description adds no extra semantics beyond what the schema already provides, which is acceptable given the single simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('a public share link for a document'). It distinguishes from sibling tools like shares_update and shares_revoke by focusing on creation, and the 'public' qualifier is an important distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to create a public share link) but does not explicitly mention alternatives or exclusions. It does not say to use shares_update for changing an existing share or shares_revoke for removal. Usage is clear from context but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verb 'List' communicates a read-only operation, which is the key behavioral trait. Without annotations, it does not disclose details like response format or access scope, but these are less critical for a no-parameter list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single three-word sentence with no filler or repetition. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list tool, the description is minimally adequate, but it does not mention return value shape or potential scope limitations. With no output schema and no annotations, more context would be helpful.
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 schema already fully covers the input. The description adds the qualifier 'all' as context, which is sufficient for this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('attachments'), clearly stating the operation. It is distinct from sibling tools like attachments_create or attachments_size, though it does not clarify the scope of 'all'.
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 it should be used when all attachments are needed, but gives no explicit guidance on when to prefer this over alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses a key behavioral trait: deletion cascades to all documents within the collection. However, it does not mention permanence, required permissions, or any other side effects (e.g., on shares or comments), leaving significant unknowns for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and its scope. It contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With just one parameter and no output schema, the description is sufficient for a simple delete tool. It clearly conveys that both the collection and its documents are affected. It could add a note about irreversibility, but this is not critical given the name and 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 lists one parameter, 'id', with a description of 'Collection ID', covering 100% of the parameter information. The tool description adds no additional meaning about the parameter, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: deleting a collection and all its documents. It uses a specific verb ('Delete') and identifies the resource ('collection'), and the added detail about documents distinguishes it from other collection 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 offers no guidance on when to use this tool versus alternatives, such as collections_update or documents_delete. There is no mention of prerequisites, conditions, or alternative tools to prefer in certain scenarios. This is a bare statement of the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states the action ('List') and gives no details about pagination behavior, filtering semantics, or what a 'membership' includes. The description is too thin to be behaviorally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. It efficiently communicates the core purpose while being appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 lack of annotations and output schema, the description alone is insufficient for a complete understanding. It omits return value expectations and usage context, leaving the agent to infer behavior from the schema and sibling tool names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully describes all five parameters. The description adds no additional meaning beyond what the schema already provides, 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 uses a specific verb ('List') and resource ('individual user memberships of a collection'), clearly distinguishing from sibling tools like collections_group_memberships (group memberships) and collections_add_user/remove_user. It precisely conveys the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'individual user memberships' implies this tool is for user memberships rather than group memberships, and the sibling names (collections_group_memberships) reinforce that context. However, there is no explicit statement of when to use this versus alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It indicates a read operation via 'Get', but does not disclose important behavioral traits such as whether the traversal is recursive, the return format, pagination, or performance implications. Minimal context beyond the core action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It front-loads the action and resource, making it immediately scannable 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?
Although the tool is simple (one parameter, no output schema), the description leaves ambiguity about what 'nested child document structure' entails. It does not clarify whether all descendants are returned, the shape of the structure, or how to interpret the response. This is a meaningful gap given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single 'id' parameter is described as 'Parent document ID'. The description itself adds no additional parameter semantics, so it neither improves nor detracts from what the schema already 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 uses a specific verb ('Get') and identifies a clear resource ('nested child document structure of a document'). It is unambiguous and distinguishes itself from sibling tools like documents_list and documents_info, which handle listing and metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need the hierarchical child structure of a document), but it does not explicitly state exclusions or contrast with alternatives like documents_info. No direct guidance on when not to use this tool is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior on its own. It only says 'List all groups' without mentioning pagination, sorting, defaults, or return format, despite the input schema suggesting paginated behavior. This is a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant wording or filler. It communicates the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse to be fully complete given the lack of output schema and pagination parameters. It doesn't explain whether the response is a list of groups, how pagination works, or what 'all groups' means in light of limit/offset. However, it's a relatively simple list tool, so it meets a minimum viable threshold.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all five parameters (sort, limit, offset, nextPath, direction) with descriptions. The tool description adds no additional parameter context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('groups') and scope ('in the workspace'), making it distinct from siblings like groups_info (specific group) and groups_memberships (membership details).
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 indicates when to use it: to list all groups. It does not explicitly mention alternatives or exclusions, but the context is unambiguous enough to guide selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. The verb 'List' implies a read-only operation, but the description doesn't disclose pagination behavior, return format, or how documents and collections are combined. It is not misleading, but it 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?
A single, clear sentence with no redundant words. The purpose is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two pagination params and no output schema, the description covers the core purpose, but it omits details like response structure, ordering, or whether both documents and collections are returned together. The presence of similar sibling tools creates ambiguity that is not resolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%—both limit and offset have clear descriptions. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource as 'user's favorite (starred) documents and collections.' It distinguishes from siblings like documents_starred by also including collections, not just documents.
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 (use when you want to list starred items), but the description provides no explicit context for when to choose this tool over similar siblings such as documents_starred or collections_list, nor does it mention 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 carries the full burden of behavioral disclosure. It conveys the state change (reactivation) but omits important details such as required permissions, reversibility, error handling, and whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for the tool's simplicity and immediately communicates the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter state-change tool, the description is minimally adequate. However, since there is no output schema or annotations, it leaves gaps around return behavior, error cases, and whether activation is idempotent, so it falls short of fully complete guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with the description 'User ID to activate.' The tool description adds no additional semantic detail beyond identifying the target as a suspended user account, so the schema already carries the 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 the specific verb 'Re-activate' and the explicit resource 'suspended user account,' making the tool's purpose unmistakable. It clearly distinguishes itself from sibling tools like users_suspend and users_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a suspended user account' provides clear context that this tool should only be used when a user is suspended, implying it is the inverse of users_suspend. However, it does not explicitly name alternatives or state exclusions for already-active users.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 must carry the full burden. 'Get' clearly indicates a read-only operation, but it does not describe the structure of the hierarchy tree, whether it includes nested collections, or any pagination/limits. It is adequate but lacks depth for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the tool's purpose. No fluff or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description gives the essential information. However, it could benefit from explaining what the hierarchy tree contains (e.g., documents only, nested structure, depth), so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter (id as 'Collection ID'), and the description's phrase 'of a collection' reaffirms the same meaning without adding new semantics. Baseline 3 is appropriate given 100% schema description 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 ('Get') and the resource ('document hierarchy tree of a collection'), which distinguishes it from sibling tools like documents_list (list documents) and collections_info (collection metadata). It is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need the full document tree of a collection), but it does not explicitly compare with alternatives or state exclusions. While sibling tools exist for related operations, no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It mentions 'fast' and 'titles only' as behavioral traits, but does not disclose pagination behavior, return format, or authentication requirements, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is perfectly front-loaded with the core action and scope. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters including pagination, no output schema, and no annotations, the description is too minimal. It does not explain the purpose of nextPath, isPublished, or collectionId, nor does it describe the return shape or how to use 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 coverage is 100% with per-parameter descriptions, so the schema already documents all four parameters. The description adds the 'titles only' scope for the query parameter but does not go 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 performs a search on document titles, with 'fast' and 'titles only' adding specificity that distinguishes it from the broader documents_search sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'titles only' implies use cases where title matching is preferred over full-text search, providing clear context without explicitly naming alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the action without indicating whether it is a read-only operation, any permission requirements, or what the response format is. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It is perfectly 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?
For a simple zero-parameter list command, the description is sufficient. It names the resource and action. It does not describe the output format, but given the tool's simplicity, this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivially covered. The description adds no parameter details, but none are needed. Baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifically states 'List available Loop commands', using a clear verb ('List') and a specific resource ('Loop commands'). This distinguishes it from sibling tools like 'loop_post' or 'telegram_commands'.
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 usage is implied: if an agent needs to see what Loop commands are available, this tool is appropriate. However, there is no explicit guidance on when to use it versus alternatives, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states only the action 'List available Loop teams' and adds no context about read-only nature, required permissions, response format, or potential side effects. This is minimal and lacks transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It is perfectly concise and front-loads the verb 'List', making it immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is adequate. It clearly identifies the resource and action. However, without annotations, it could mention expected return type or any access prerequisites, but the simplicity of the operation makes the description mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema coverage (empty properties). With no parameters to describe, the description does not need to add parameter details, and the baseline of 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 'List available Loop teams.' uses a specific verb 'List' and identifies the resource 'Loop teams', which clearly differentiates it from sibling tools like loop_channels, loop_commands, and loop_post. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, but the action itself implies usage: to list teams. There are no exclusions or references to other loop_* tools, so it meets the 'implied usage' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly indicates a read-only operation via 'List', but it does not disclose additional traits such as permission requirements, whether indirect access (e.g., via groups) is included, or pagination behavior. It does not contradict any structured information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It fully conveys the tool's purpose while remaining 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?
For a simple tool with 2 parameters and no output schema, the description adequately conveys the operation. It could have added nuance about whether the user list includes group-based access, but overall it is sufficiently complete for straightforward usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters: 'id' (Document ID) and 'query' (Filter users by name). The description adds no extra 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource (users) and scope (who have access to a document). This distinguishes it from sibling tools like documents_add_user and documents_remove_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you need to see all users with access to a document, but it does not provide explicit when-not-to-use guidance or mention alternatives such as documents_info or shares_list. The context is clear, though exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It appropriately frames the operation as read-only informational retrieval, which is transparent. It doesn't mention error cases, but for this trivial, side-effect-free operation, no further disclosure 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word adds value, making it an exemplar of 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?
For a zero-parameter, no-output-schema tool, the description is entirely self-sufficient. It states exactly what the tool returns (user and team info), giving an agent everything needed to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description correctly focuses on the output rather than inputs, and there is no parameter information to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('authentication details') with a clear scope ('current API key'), followed by concrete examples ('current user, team info'). It fully distinguishes this from sibling tools like auth_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context for when to use the tool is clear: whenever the agent needs authentication details for the current API key. No exclusions or alternative tools are mentioned, but for a simple info getter this is sufficient.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NikitaMurugov/yonote-mcp'

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