Search, fetch (with provenance), scan, and convert AI instruction files for agents.
Report which sources are connected to the caller's TomeVault workspace and return the link that starts connecting another. Connecting requires the person to approve access in their browser, so this returns a link for them to open rather than completing it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses that the tool does not complete the connection, requires the person to approve access in their browser, and returns a link for the user to open. This prevents the common misconception that the tool performs the connection directly. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the core purpose before explaining the important limitation. The second sentence slightly repeats the idea of returning a link, but it justifies that repetition by explaining the browser-approval requirement, so there is no significant waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description fully covers what the tool reports, what it returns, and why it does not complete the connection. An agent has enough information to invoke it correctly and set proper expectations for the user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, so there is no parameter-level information for the description to add. With no inputs required, the baseline for zero-parameter tools applies and the description appropriately says nothing about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it reports which sources are connected to the caller's TomeVault workspace and returns a link to start connecting another. It also clearly distinguishes its behavior from actually completing a connection, which prevents confusion with the tool's name or with sibling tools like deliver_to_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: to check existing source connections or to obtain a link for a new connection. It also explains the browser-approval requirement, so an agent knows to surface the link to the user rather than expect a completed connection. It does not explicitly name alternatives or exclusions, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert pasted instruction-file text into another tool's format (claude_md, agents_md, cursor_mdc, gemini_md, copilot_instructions, windsurf_rules, skill_md). The same instructions, ready for any tool.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional title for the converted file's heading/frontmatter. | |
| content | Yes | The raw instruction-file text to convert. | |
| to_format | Yes | The target tool format. | |
| description | No | Optional one-line description for the converted file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's alignment is sufficient. It adds no further behavioral details (e.g., idempotency, rate limits) but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence delivers core purpose, second sentence is slightly redundant but still brief. No wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should hint at return format. It does not mention that the tool returns the converted text. Otherwise, coverage of inputs and purpose is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add new semantic info beyond reinforcing purpose; the format list is already in the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb ('Convert'), resource ('pasted instruction-file text'), and target formats (specific list). It distinguishes from sibling tools (get_provenance, get_tome, etc.) which are about retrieval, not format conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use case (convert between tool formats) but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deliver a TomeVault file's approved version back to the caller's connected Google Drive, so the corrected file reaches the place their team reads it. Sends the approved version, which is not always the newest one. Requires a connected Drive.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | The vault file id, from list_vault_items. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive/non-idempotent/read-write behavior, so the bar is lower. The description adds valuable traits beyond the annotations: it sends the approved version rather than the newest one, and it requires a connected Drive. This gives an agent accurate expectations about a non-obvious version-selection behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states action, resource, destination, and purpose; the second clarifies the version nuance; the third states the prerequisite. No fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with a safety profile covered by annotations, the description is largely complete: it names the destination, the version selected, and a hard prerequisite. The main gap is that it doesn't specify destination side effects (overwrite vs. create a new file on Drive) or return value, but with no output schema and a clear purpose these are minor omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The single parameter item_id is already documented in the schema as 'The vault file id, from list_vault_items.' The description adds no parameter-specific details beyond the schema, though its version-selection caveat subtly clarifies what the item_id refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb, resource, and destination: delivering a TomeVault file's approved version to the caller's connected Google Drive. The 'caller's connected Drive' scope and the emphasis on the approved (not necessarily newest) version clearly differentiate it from sibling tools like save_vault_version or get_vault_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: this is for getting a corrected/approved file to the place the team reads it, and it notes the prerequisite of a connected Drive. It does not explicitly name alternatives or exclusion conditions, but the purpose statement makes the intended use fairly unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which plan the caller's TomeVault workspace is on, who is on it, what is included, and how much of that is unused. Read only: it cannot change a plan or spend money. It does not report a seat count, because seats bill on approved authority rather than headcount and the exact figure is on their billing page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds valuable context: the operation cannot change installed plans or spend money, and the seat count exclusion is explained with a rationale (approved-authority billing). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: purpose, safety, and a key limitation. The primary function is front-loaded, with no wasted words or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description already enumerates the report contents (plan, members, inclusions, unused amounts) and a notable exclusion (seat count). With no output schema, this is reasonably complete for an agent to invoke and interpret results; a small gap is that the exact return format is not specified, but the semantic contents are clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there is nothing to document. The description's lack of parameter discussion is appropriate; a baseline of 4 is warranted for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Report') and defines the exact resource scope: the caller's TomeVault workspace's billing plan, its members, included items, and unused amounts. It explicitly distinguishes itself from a seat-count report, which sets it apart from potential sibling tools like spotcheck_costs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage intent is clear through the stated purpose: use when the caller needs billing summary information. It provides strong when-not guidance by declaring it cannot change plans, spend money, or report seat counts, and points to the billing page for the exact seat figure. It does not name an alternative tool, but the negative constraints are sufficient for agent routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the signed attestation record alone for a tome: quality grade, security scan grade and flags, decay risk, source registry, the content hash it is bound to, and the signing key id for offline verification.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | GitHub repository name. | |
| owner | Yes | GitHub owner or org. | |
| skill_path | No | Address a specific skill within the repo, e.g. skills/foo. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds value by specifying what the attestation record contains (quality grade, security scan, etc.) and mentions offline verification, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists fields, but it is slightly dense; could be split for clarity but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must fully explain the return value; it lists fields but lacks structure or types, and no error conditions are mentioned. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions; the tool description does not add meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return the signed attestation record alone for a tome' with a specific verb and resource, and lists exact fields, distinguishing it from siblings like get_tome and verify_attestation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for 'offline verification' but provides no explicit when-to-use or when-not-to-use guidance, nor contrasts with alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one tome's content in a specific agent format (default claude_md). Every response carries the provenance verdict: quality grade, security scan grade, decay risk, and the content hash it is bound to.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | GitHub repository name. | |
| owner | Yes | GitHub owner or org. | |
| format | No | Output format, e.g. claude_md, agents_md, skill_md. | claude_md |
| skill_path | No | Fetch a specific skill within the repo (the skill_path from a search_tomes result). Omit for the repo's primary unit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint; the description confirms a read operation and adds detail about the provenance verdict (quality grade, security scan, etc.), which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core purpose and add key response information without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main functionality and response fields, but lacks details on error cases or what happens when a tome is not found. Without an output schema, some ambiguity remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, but the description adds context: default format 'claude_md' and skill_path origin from search_tomes results, enhancing meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch one tome's content in a specific agent format', providing a clear verb and resource. It distinguishes itself from siblings like search_tomes and get_provenance by focusing on retrieving content with provenance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. While the context makes it suitable for fetching a single tome with provenance, it lacks direct comparisons to siblings like search_tomes or get_provenance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one of your TomeVault items by id, with its content. Returns the version the file's maintainer approved, which is not always the newest one. Requires a vault access token with the items:read scope. Encrypted items are not retrievable and return not found, indistinguishable from a missing id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The vault item id, from list_vault_items. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses three meaningful behaviors: it returns the maintainer-approved version which may not be newest, it requires items:read scope, and encrypted items return not found so they are indistinguishable from missing ids. This is substantial behavioral context that the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Each sentence earns its place: action, version behavior, auth scoping, and encryption/error behavior. The key operation is front-loaded in the first sentence with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-required-parameter read tool with no output schema, the description is unusually complete. It covers prerequisites (token scope), version-selection behavior, and edge case (encrypted items and identical not-found error), so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the id parameter already has its own description ('The vault item id, from list_vault_items'). The tool description adds 'by id' and emphasizes content retrieval, but does not add new semantic detail about the id parameter beyond what the schema already provides, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific action and resource: 'Fetch one of your TomeVault items by id, with its content.' This clearly separates it from list_vault_items (which lists), get_tome, and other siblings, and the by-id singular access makes its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the use case: an agent has a vault item id and wants its content. It also states the required items:read scope. However, it never names alternatives or gives explicit 'use X when...' guidance to distinguish from get_tome or list_vault_items, so the when-to-use info is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarise the caller's TomeVault workspace: how many files are held, what sources are connected, how many people are on it, and what is not yet covered. Call this before answering questions about their setup, and before suggesting a next step, so the answer describes their real state rather than a guess. gaps lists what is missing and is as important as the counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is to add context beyond those. It adds the caller-scoping detail, the composition of the summary, and the notable behavioral cue that '`gaps` lists what is missing and is as important as the counts' — telling the agent not to deprioritize the gap field. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, when to call it, and a field-level emphasis cue. The core purpose is front-loaded and there is zero filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description compensates well by enumerating what the summary contains and naming the `gaps` field explicitly. It doesn't specify exact field names or value types, but the conceptual coverage is sufficient for an agent to invoke it and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters, the baseline is 4 and the schema needs no enrichment. The description appropriately focuses on what the tool does with its implicit caller context rather than inventing parameter documentation that isn't needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Summarise') with a clearly bounded resource ('the caller's TomeVault workspace') and enumerates the exact contents of the summary (file counts, connected sources, member count, coverage gaps). This distinguishes it from siblings like get_billing_summary, list_members, and list_vault_items, which each cover only a slice of what this tool aggregates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-call guidance: 'Call this before answering questions about their setup, and before suggesting a next step, so the answer describes their real state rather than a guess.' This is actionable and explains the rationale (avoiding hallucinated state). It does not name specific alternative tools or exclusion conditions, but the tool's role as an opener/summary makes that less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite a colleague to the caller's TomeVault workspace by email. Sends them a join link. Requires an admin. The join link is emailed to them and is never returned here.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The colleague's email address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only generic flags (readOnly=false, destructive=true, idempotent=false, openWorld=true). The description adds concrete behavior: a join link is emailed and 'is never returned here,' explaining the external side effect and managing output expectations. This is valuable beyond annotations, though it does not cover failure/duplicate behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences with no unnecessary words: action, effect, prerequisit, and return behavior are each given their own concise sentence. Information is front-loaded and every sentence adds a distinct fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, the description covers purpose, admin requirement, email delivery, and the notable absence of the link in the response. Minor gaps exist around duplicate invites and error cases, but they are unlikely to prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the email parameter is fully described as 'The colleague's email address.' The description clarifies that 'by email' is the delivery mechanism, but this does not materially add to the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Invite'), a resource ('colleague to... workspace'), and the mechanism ('by email'), clearly distinguishing it from read-only siblings like list_members. It is immediately obvious what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the key prerequisite 'Requires an admin,' giving an agent clear condition for when the call is permissible. There are no true alternatives among siblings, so explicit exclusions are unnecessary, but the usage context is otherwise implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a signed TomeVault certificate for one organisation (a client folder). It covers every file in that folder that has a matching record, lists the rest with the reason they are not covered, and never re-grades: every grade comes from a record already signed. Only works for a client whose certification is already active; it cannot activate one, because that costs money.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Display title for the certificate. Not part of the signature. | |
| client_id | Yes | The client id, from list_certifications. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by explaining that grades are never recalculated ('every grade comes from a record already signed') and that output separates covered files from uncovered ones with reasons. The destructiveHint/readOnly annotations already signal mutation risk, and the description adds the non-re-grading boundary, so there is no contradiction; it just doesn't elaborate what destructive side effects, if any, occur beyond issuing the certificate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences front-load the core action and scope, then the constraints. Every clause earns its place—there is no filler, trademark, or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers purpose, scope, active-certification precondition, cost-based exclusion, and expected output components. Given the annotations and full parameter schema, an agent has enough to invoke correctly, though the actual return shape and format of the issued certificate aren't stated since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters thoroughly (client_id from list_certifications, title not part of the signature). The description adds only the alias that a client is a folder/organisation, so its contribution over the schema is minor; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact action and target: 'issue a signed TomeVault certificate for one organisation (a client folder).' The next clauses add distinctive scope rules (matching records covered, others listed with reasons, no re-grading) that separate it from listing/verification siblings such as list_certifications and verify_attestation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit precondition and exclusion: it only works when the client's certification is already active and cannot be used to activate one because activation costs money. This tells an agent when not to call, though it doesn't name an alternative activation tool; the schema's client_id reference to list_certifications is the only pointer for setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the clients in the caller's TomeVault workspace, which of them have certification active, and which certificates have been issued. Reports what activating would cost. It cannot activate anything: that is a paid, human decision made on the website.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safety, and the description reinforces and expands it by stating the tool cannot activate anything and that activation is a paid, human decision made on the website. This adds meaningful side-effect context beyond the annotation. It does not address the openWorldHint implication, but the core behavioral boundary is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the action and resource. Each sentence adds a distinct fact: what is listed, what cost information is reported, and what the tool cannot do. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool, the description is complete enough. It states what the tool returns (clients, certification-active flags, issued certificates, activation cost) and what it cannot do. There is no output schema, but the returned content is described clearly enough for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. With no parameters to document, the description has nothing to add about argument semantics, and no information is missing for calling the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List the clients in the caller's TomeVault workspace', and then defines the exact scope: certification-active status, issued certificates, and activation cost. This clearly distinguishes it from sibling tools like list_members or get_billing_summary, which focus on membership or billing rather than certification status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes clear usage context: use this to inspect client certification status and activation cost. It also provides an explicit when-not: 'It cannot activate anything: that is a paid, human decision made on the website.' However, it does not name alternative sibling tools or describe when another tool would be preferred, so it falls just short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List who is on the caller's TomeVault workspace and which invitations are still outstanding. Returns roles and join dates, not the email addresses of people who have already joined.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so no contradiction exists. The description adds meaningful behavioral detail: it returns roles and join dates, and explicitly excludes email addresses of joined members, preventing an agent from assuming that information is included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the primary function, and the second adds return scope and a key limitation. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool, the description covers the key facts: what is listed, what fields are returned, and what is intentionally omitted. Without an output schema, it could optionally describe formatting or entry structure, but the essentials are present and no critical invocation detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% schema description coverage, so there is nothing for the description to clarify. The baseline of 4 applies because parameter semantics are fully trivially handled by the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 ('members on the caller's TomeVault workspace'), and also clarifies the scope by including outstanding invitations. It distinguishes itself from siblings like list_vault_items and get_workspace_status by focusing on membership data and explicitly noting what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: whenever an agent needs workspace membership or outstanding invitations. However, it does not explicitly state when to prefer this over siblings such as get_workspace_status or invite_member, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the items in your TomeVault that this token can read. Requires a vault access token with the items:read scope. Encrypted (private) items are never listed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: the scope requirement and the important detail that encrypted items are never listed. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. First sentence states core purpose, second adds necessary scope and exception. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input and no output schema, the description covers the main purpose and a key behavioral exception. However, it doesn't mention that the result is a list of items or any pagination details. Still adequate for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The tool description does not mention the 'limit' parameter or its meaning (pagination control). Although the schema provides bounds, the description should compensate for the lack of schema descriptions, but it fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'list' and resource 'items in your TomeVault', with explicit scope requirement and exception for encrypted items. Distinguishes well from siblings like get_vault_item (singular) and get_tome (single object).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit requirement for vault access token with items:read scope, and clarifies that encrypted items will never be listed. Does not explicitly mention alternatives, but the context of a list operation vs. single-item retrieval is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save corrected content as a new version of one of your TomeVault files. The previous version is kept and the file is re-checked. Returns the new version number and the verdict, never the file content.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The complete corrected file. Partial content would truncate the file. | |
| item_id | Yes | The vault file id, from list_vault_items. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it discloses that the previous version is kept, that the file is re-checked as a side effect, and that the response contains only the version number and verdict, never file content. This contextualizes the destructiveHint=true and gives the agent a concrete safety and return-behavior model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the action, the side effect/versioning behavior, and the return payload. It is front-loaded with the primary purpose and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers the essential context: what to pass (via schema + 'corrected content'), what side effects occur (version kept, re-check), and what is returned (version number and verdict, not content). No critical operational information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with item_id and content already well documented (e.g., 'complete corrected file' and 'partial content would truncate'). The tool description reinforces 'corrected content' but does not add material parameter-level 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('save corrected content as a new version') on a specific resource ('one of your TomeVault files'), and clarifies that this is a versioning write, not an overwrite or read. It is clearly differentiated from the sibling read/scan/convert tools, even though no sibling is named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'corrected content' establishes when the tool is appropriate, and the description implies it is the write step after content has been corrected. It does not explicitly name alternatives or exclusions, but the use case is clear enough for an agent to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan submitted instruction-file text for safety, clarity, loadability, and cross-model consistency, and return a verdict with findings. Each finding carries a severity: fail means the rule does not load, info means it loads but is wrong in a way worth fixing, such as naming a retired model. Report both. Only an empty findings array means nothing was found. Use before loading a third-party file. Consistency findings are PREDICTIONS (divergence risks across models/tools), never verified facts. The submitted text is scanned and discarded, never stored.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional display name, e.g. CLAUDE.md. | |
| text | Yes | Raw instruction-file text to scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is supplemented with substantial behavioral detail: the submitted text 'is scanned and discarded, never stored,' and consistency findings are labeled as PREDICTIONS, not verified facts. It also defines the fail/info severity semantics, going well beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then adds severity semantics, result interpretation, usage timing, prediction caveat, and privacy guarantee. Every sentence carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately explains return semantics: a verdict with findings, severity levels, and the meaning of an empty findings array. Combined with schema-covered parameters and read-only annotations, the definition gives an agent everything needed to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both name and text documented in the input schema. The description adds no parameter-specific syntax or formatting details, so the baseline of 3 applies; it does not compensate for or need to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Scan submitted instruction-file text') and names the four analysis dimensions (safety, clarity, loadability, and cross-model consistency), then states the output ('a verdict with findings'). This clearly distinguishes it from sibling tools like convert_content, get_provenance, and verify_attestation, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Use before loading a third-party file.' This is clear contextual guidance, though it does not enumerate excluded cases or explicitly compare against sibling tools for when not to use them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search TomeVault for agent context files (tomes, configs, skills) by a task description. Filter by format, kind, and quality grade. Returns ranked matches with owner/repo, grade, and available formats, not file contents.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | tome = full project config + skills; config = one config file; skill = one skill. | |
| grade | No | Screen by graded quality tier. | |
| limit | No | ||
| query | Yes | Free-text task or topic to match. | |
| format | No | Target tool format, e.g. claude_md, agents_md, cursor_mdc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds behavioral context: returns ranked matches with owner/repo, grade, and available formats, explicitly noting it does not return file contents. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with main purpose; each sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description sufficiently explains return values (ranked matches with metadata). Covers purpose, parameters (aided by schema), and behavioral expectations. A minor gap is lack of pagination or total results info, but not critical for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%) with descriptions for each parameter. Description mentions filtering by format, kind, and quality grade, but adds minimal extra meaning beyond what schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Search' and resource 'TomeVault for agent context files (tomes, configs, skills)'. It specifies it searches by task description, and explicitly distinguishes from siblings like get_tome by noting it returns ranked matches with metadata, not file contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides clear context: search by task description, filter by format/kind/grade. It implicitly differentiates from sibling tools (single-item retrieval) but does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a TomeVault attestation document (the contents of a repo's .tome/attestation.json). Confirms the detached signature is genuinely TomeVault's against the published key, and, if the signed file's text is supplied, that the file has not drifted since it was signed. Returns the signed verdict; consistency in it is a PREDICTION (cross-model divergence risk), never a verified fact. Nothing submitted is stored.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | Optional: the instruction file the attestation signs, to also confirm it has not changed. | |
| attestation | Yes | The .tome/attestation.json document text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures beyond annotations: states that consistency is a PREDICTION (not a verified fact) and that nothing submitted is stored. Annotations already indicate readOnlyHint=true, and the description adds important caveats about the interpretation of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences that front-load the purpose and provide necessary details without extraneous text. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no output schema) and presence of annotations, the description is fully sufficient. It explains inputs, process, output (signed verdict), and a critical caveat about the prediction nature of consistency. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description provides additional context for the 'content' parameter (the instruction file). While the schema already describes both parameters, the description clarifies their roles beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool verifies a TomeVault attestation document, specifying the actions: confirming the signature's authenticity and checking file integrity. The verb 'verify' and resource 'attestation document' are explicit, distinguishing it from sibling tools like convert_content or get_provenance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool (verification of attestation and content consistency). Does not explicitly mention when not to use it or direct alternatives among siblings, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
issue_certificate2 fields changedInput schema / properties / item_idsRemoved value: -{
- "description": "Ids of stored files in that client's folder, from list_vault_items.",
- "items": {
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- },
- "maxItems": 25,
- "minItems": 1,
- "type": "array"
-}Input schema / requiredPrevious value: -[
- "client_id",
- "item_ids"
-]New value: +[
+ "client_id"
+]issue_certificatelist_certificationsconnect_sourcedeliver_to_sourceget_billing_summaryget_workspace_statusinvite_memberlist_memberssave_vault_versionverify_attestationconvert_contentget_provenanceget_tomeget_vault_itemlist_vault_itemsscan_contentsearch_tomesClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Securely search and manage workspace context files for AI agents and teams.
Artifact store for AI agents — read, write, and search files by path; share by rendered URL.
Machine-readable utilities and datasets for AI agents.
AI Agent Source Registry. 288K+ curated sources for agentic search and discovery.
Add one secure layer between your agents and this server.
Several tools overlap in purpose: get_tome and get_vault_item both fetch a single item's content without clarifying the relationship between tomes and vault items, and connect_source overlaps with get_workspace_status for reporting connected sources. The detailed descriptions help, but the boundaries between these pairs remain unclear.
Most tool names follow a clear snake_case verb_noun pattern (get_tome, list_vault_items, scan_content, verify_attestation). There are minor deviations such as deliver_to_source with its preposition and connect_source whose name undersells its reporting behavior, but the overall convention is predictable.
Fifteen tools is within a reasonable range for a workspace, content-management, and attestation service, and most tools map to a distinct concern. The count feels slightly heavy because a few tools (get_tome vs get_vault_item, connect_source vs get_workspace_status) could potentially be consolidated.
Read, search, scan, versioning, and delivery workflows are well covered, along with members, billing, and workspace status. However, there are notable lifecycle gaps: no disconnect/remove for sources, no remove or role-update for members, and no delete or explicit approve action for vault items/versions.