Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that authentication uses env vars, returns a status message, and that the token is managed automatically for subsequent calls. This covers key behavioral traits without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with purpose. Every sentence adds necessary information without 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?

Given zero parameters and an output schema (though not shown), the description sufficiently explains authentication flow, environment variable usage, and automatic token management. It is complete for a simple auth tool with no siblings in the same domain.

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 baseline is 4. The description adds value by explaining that environment variables are used, which is not in 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 clearly states 'Authenticate with the Relay Control Plane', specifying the verb and resource. It is distinct from sibling tools that all perform file or document operations.

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 explains the use of environment variables (RELAY_EMAIL, RELAY_PASSWORD) and notes that the token is managed internally, implying it should be called first. No explicit exclusions or alternatives are needed given no sibling auth tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 clearly states the destructive nature ('Delete'), the effect on metadata registry, and the sync behavior with Obsidian. It also mentions the return format. However, it does not cover permanence or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a front-loaded summary. Every sentence provides value: one-line purpose, two behavioral lines, and a structured Args section. No 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?

The description covers purpose, behavior, parameters, and return value. Given the simplicity of the tool (delete a file), it is nearly complete. Minor missing details like error handling do not detract significantly.

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%, but the description fully explains both parameters: share_id as UUID and file_path with an example. This adds significant meaning beyond the schema titles.

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 begins with a clear verb and resource: 'Delete a file from a folder share.' It distinguishes from siblings like read_document and upsert_file by specifying deletion and metadata removal. Additional context about Obsidian sync further clarifies the tool's effect.

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 when to use (to delete a file), but does not explicitly state when not to use or mention alternatives among siblings. No prerequisites or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavioral traits. It only mentions listing files, not whether it's read-only, requires auth, or any side effects. Incomplete for an unannotated tool.

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?

Very concise: one-sentence purpose, Args/Returns format. Every sentence is informative with no redundancy. Front-loaded with purpose.

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 output schema exists (though not detailed), the description adequately covers return structure. Simple tool with one param, but missing error conditions or usage notes. Overall sufficient.

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 description adds meaning to the sole parameter share_id by calling it a 'UUID of the folder share', which the schema (0% coverage) lacked. Effectively clarifies the parameter's purpose.

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 the tool lists files in a folder share, distinguishing it from siblings like list_shares (shares list) and read_file (single file). It specifies the argument and return structure.

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 versus alternatives. The required parameter hint is implicit but not enough; lacks context like needing a share_id from list_shares.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses the return format and parameter behavior but lacks details on read-only nature, authentication requirements, or rate limits. The verb 'list' implies a read operation, but not explicitly.

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 concise with a front-loaded main sentence, followed by structured Args and Returns sections. No 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?

For a simple list tool, the description covers the purpose, parameters, and return format. It lacks details on pagination, error handling, or limits, but is adequate given the tool's simplicity and no annotations.

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 descriptions are missing (0% coverage), but the description's Args section clearly explains each parameter's purpose (kind filter, owned_only filter). This compensates for the schema gap.

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 starts with 'List all accessible shares', clearly stating the verb (list) and resource (shares). It is distinct from sibling tools like list_files and delete_file.

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 does not explicitly state when to use this tool versus alternatives. It provides parameter guidance but lacks 'when not to use' or mention of alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavior like defaulting doc_id to share_id for doc shares, and returns JSON with specific fields. No annotations exist, so description carries burden. Could be more explicit about read-only nature.

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?

Description is well-structured with a summary line, usage cases, and an Args section. It is informative but slightly long; could be more concise without losing clarity.

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 an output schema exists and sibling tools are listed, the description covers all necessary context: parameters, defaults, and when to use alternatives. It is complete for a read 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?

Adds substantial meaning beyond the input schema: explains share_id as UUID for ACL check, doc_id defaults, and key as Yjs shared type key. For 0% schema coverage, this fully compensates.

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 the tool reads document content by doc_id and is low-level. It differentiates from sibling tools like read_file by specifying when to use each.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidelines: for doc shares omit doc_id, for folder shares pass doc_id from list_files, and prefers read_file for folder shares. Also clarifies defaults and arguments.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool resolves path to doc_id automatically, which is a behavioral trait. However, with no annotations provided, it fails to mention whether the operation is read-only, any authorization requirements, error behavior, or side effects. The read operation is implied but not explicitly stated.

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 concise and well-structured: a brief statement of purpose, a key behavioral note, and clear parameter and return explanations. Every sentence adds value, making it efficient for an AI agent to parse.

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 tool's simplicity and the presence of an output schema (though not shown), the description covers the main functionality, return fields, and paths. It could mention edge cases like missing files or path formats, but overall it's sufficiently complete for a read 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?

The input schema has 0% description coverage for parameters. The description compensates by explaining share_id as UUID and file_path with an example (e.g., 'Marketing/plan.md'). This adds significant meaning beyond the bare schema, though no validation details are given.

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 that the tool reads a file from a folder share using a path. It specifies the resource ('folder share') and verb ('Read'), and differentiates from siblings like list_files and read_document by being the recommended method for reading files from folder shares.

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 says 'This is the recommended way to read files from folder shares,' implying it's preferred over alternatives, but it does not explicitly state when to avoid this tool or mention specific alternatives like read_document. More explicit guidance would be beneficial.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses the PUT/POST behavior and the returned operation field. It does not mention side effects, error conditions, or permission requirements, which is acceptable for a straightforward file write but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a summary line, a bullet list of arguments, and a return statement. It is concise and front-loaded. One could slightly tighten the bullet list, but overall it is efficient.

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 tool has an output schema, the description's brief return explanation suffices. All 3 required parameters are explained, and the behavior is clear. It is complete enough for a tool with moderate complexity.

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 description provides clear, semantic explanations for all three parameters (share_id as UUID, file_path as path, content as text) beyond the schema titles. Since schema coverage is 0%, the description fully compensates.

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 the action ('Create or update a file') and resource ('in a folder share'). It distinguishes itself from siblings like delete_file, read_file, and write_document by being the recommended write tool. The verb-resource combination 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the tool automatically detects file existence and uses PUT/POST accordingly. It marks itself as 'the recommended way to write files to folder shares,' providing clear context. However, it does not explicitly state when to use alternatives like write_document, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but description reveals key behavior: 'replaces entire document', mentions ACL check via share_id. Could specify if document must exist, but sufficient 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences plus bullet-like arg list. No wasted words, well-organized.

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 core usage, parameter roles, and return format. Missing edge cases like non-existent doc, but adequate for a simple write 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 has 0% description coverage; description adds meaning for all parameters: share_id for ACL, doc_id as UUID, content as full text, key default. Also explains return fields.

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 'Write content to a document' with specific resource (doc_id) and scope ('doc shares only'), distinguishing it from sibling upsert_file.

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?

Explicitly tells when to use this tool (doc shares) and when not ('For folder shares, use upsert_file instead'), providing a clear alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.