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

With no annotations, the description carries the burden of behavioral disclosure. It explains what the tool does (searches for .scriv folders), where it searches (common locations), and that it returns a list of paths. While it doesn't mention performance or side effects, the read-only nature is implied by 'Find' and the return description, which is adequate for this simple 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?

The description is concise and well-structured. It front-loads the purpose in one sentence, then provides a brief explanation, parameter details, and return value. Every sentence serves a purpose without redundancy, making it easy for an agent to parse quickly.

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 fully covers the tool's context: purpose, usage, parameter semantics, and return type. It even names the follow-up tool (open_project). For a simple, optional-parameter discovery tool, this is complete and requires no additional information for an agent to use 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?

The input schema provides only a parameter name and type, with 0% schema description coverage. The description fully compensates by explaining the parameter's purpose and behavior: 'search_path: Optional specific folder to search. If not provided, searches common locations like Documents, Dropbox, iCloud.' This adds significant 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 clearly states the tool's function: 'Find Scrivener projects on your computer.' It specifies the resource (.scriv folders) and the scope (common locations), and it distinguishes itself from sibling tools like open_project by focusing on discovery.

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 provides clear usage context: 'Use this to discover available projects, then use open_project to load one.' It names an alternative tool for the next step, though it doesn't explicitly state when not to use this tool. This is strong guidance for a discovery tool.

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, the description carries the behavioral burden. It does disclose the return behavior ('notes text, or a message if no notes exist') but omits edge cases like invalid identifiers or multiple matches. The read-only nature is implied by 'Get' but not made explicit.

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 clear Args/Returns sections. The sentence about Scrivener inspector notes provides useful context, though it slightly extends beyond pure functional description. Overall efficient and readable.

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 1-parameter tool with an output schema, the description is fairly complete. It explains what notes are and what the return value looks like. The only gap is lack of explicit usage differentiation from sibling tools, but the simplicity of the tool reduces the need.

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?

Despite 0% schema coverage, the description defines 'identifier' as 'Document title, path, or UUID', adding meaningful semantic content beyond the raw schema. It gives the agent concrete information on acceptable identifier formats.

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 ('Get') and names the exact resource ('document notes (inspector notes)'). It also clarifies that these are inspector notes (author notes, research, reminders), distinguishing this from sibling tools like read_document (body content) and get_synopsis.

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 provides context about when notes are relevant (inspector panel, author notes, research) but does not explicitly state when to choose this tool over alternatives like read_document or get_synopsis. Usage is implied but not directly compared.

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 the full burden. It discloses the return behavior including the fallback 'or a message if no synopsis exists,' which is good. However, it does not explicitly state read-only semantics or permission requirements, though the verb 'Get' implies a non-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.

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

The description is concise and well-structured, with a clear opening statement, contextual explanation, and separate Args/Returns sections. Every sentence contributes useful 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?

For a single-parameter getter, the description adequately covers the identifier format, the return value, and the no-synopsis fallback. The presence of an output schema further reduces the need to detail return structures, making this complete for its 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 schema only defines 'identifier' as a string with 0% coverage. The description compensates by specifying 'Document title, path, or UUID,' giving the parameter concrete meaning and accepted formats beyond what the schema provides.

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 it 'Get[s] the synopsis (short summary) of a document,' using a specific verb and resource. It further distinguishes from siblings like read_document and write_synopsis by emphasizing the synopsis specifically.

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 'Useful for understanding scene/chapter summaries' provides clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, 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.

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

The description makes it clear this is a read-only operation ('Get'), and describes the return value (breakdown by folder/chapter). With no annotations, this adds sufficient behavioral context, though it does not mention error behavior or performance characteristics.

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 no wasted sentences. It uses a clear structure with Args and Returns, and explains the default behavior efficiently.

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 read-only tool with one optional parameter, the description covers the core function, the parameter semantics, and the return value. It is complete enough for an agent to use correctly, though it could mention whether folder_path is relative to project root.

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 thoroughly explains the folder_path parameter, stating it is optional, what it does, and what happens when omitted (default to entire manuscript). This goes beyond the schema's minimal type definition.

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 gets word count statistics for the project or a specific folder, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on word counts rather than content reading or search.

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 mention when to use this tool versus other project tools. The usage is implied by the purpose, but no alternatives 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the hierarchical tree output, use of emojis for folders/documents, and the 'Include in Compile' marker, which is valuable context. It does not mention error handling or side effects, but as a read-only list operation, this is sufficient.

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 with clear Args and Returns sections. Every sentence contributes meaningful information, and the key purpose is stated in the opening sentence.

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 tool has a simple input (one optional parameter) and an output schema, and the description provides complete coverage of the tool's behavior, including return format and optional filtering. Nothing essential 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 0%, but the description fully compensates by explaining the folder_path parameter's format with an example, its optionality, and the behavior when omitted. This goes well beyond the schema's minimal definition.

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 ('binder structure of the Scrivener project'), clearly distinguishing it from siblings like read_document and search_project. The reference to Scrivener's binder sidebar reinforces the unique purpose.

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

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

The description clearly states when to use the tool (to view binder structure) and explains the optional folder_path parameter, but does not explicitly mention alternatives or when not to use it. The context is clear, but exclusions are absent.

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 only mentions a return confirmation, but fails to disclose side effects (e.g., loading/locking the project), error behavior, or required permissions. This is minimal transparency for an operation like 'open'.

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 extremely concise and well-structured with Args and Returns sections. Every sentence provides useful information, and there is no redundancy or 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?

Despite having a simple one-parameter schema, the description lacks essential context: no usage guidance, no state-change implications, and no clarity on how this tool fits with siblings. The output schema covers return values, but the description alone is insufficient for an agent to use it appropriately.

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 schema has no parameter descriptions, but the description adds 'path: Path to the .scriv folder', which clarifies the expected format. This is crucial for correct use, though it does not elaborate on constraints like absolute vs relative paths.

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 'Open a Scrivener project' with a specific verb and resource. It implicitly distinguishes from siblings like find_projects or read_document, but does not explicitly contrast them, so it misses the top score.

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 provides no guidance on when to use this tool versus alternatives such as find_projects or scan_project. There is no mention of prerequisites, workflow context, 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.

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

With no annotations, the description carries the full burden and does well: it states that all documents within the chapter are read in binder order, that titles can be included, and it warns about timeouts for large projects. This goes beyond the basic schema and provides useful 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.

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

The description is well-structured with a clear opening sentence, a warning, and an Args/Returns breakdown. It is concise, with no redundant or filler content, and 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?

The description covers prerequisites (scan_project), performance guidance, parameter details, and return behavior. Given the tool's moderate complexity and the presence of an output schema, it is sufficiently complete for effective use.

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, but the Args section provides thorough explanations for both parameters, including the type and default for include_titles and concrete path examples for chapter. This fully 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 clearly identifies the tool as reading a specific chapter or section of the manuscript, with details that it reads all documents in the folder in binder order. This distinguishes it from sibling read_document by scope, and the verb+resource structure is specific.

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 instructs to read one chapter at a time for large projects to avoid timeouts and directs users to run scan_project first to see available chapters. While it doesn't name an alternative for reading single documents, the guidance is clear and actionable.

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, the description carries full burden for behavioral disclosure. It reveals the return format (plain text with metadata header) and the supported identifier types, providing insight into lookup behavior. However, it does not mention error handling or uniqueness requirements, which would increase transparency further.

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 clear summary, an Args section, and a Returns section. Every line adds value, and there is no irrelevant information.

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 tool is simple (one parameter), and the description covers identification and return format. The presence of an output schema further specifies return structure. However, it does not address what happens if the identifier is ambiguous or not found, leaving a minor gap.

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 only defines 'identifier' as a string. The description compensates by explaining the three valid forms (title, path, UUID) with concrete examples, significantly enriching the parameter's 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 clearly states the tool reads the content of a specific document, with a precise verb ('read') and resource ('document'). It further specifies the accepted identifier types (title, path, UUID), which distinguishes it from sibling tools like read_chapter or get_notes.

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 guidance is provided on when to use this tool versus alternatives such as read_chapter or get_notes. The description only explains how to specify the identifier, but not under what circumstances to choose this tool over others.

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

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

With no annotations, the description carries the full burden. It discloses that scanning returns a structured overview, does not load every document into memory, and scans the entire Draft/Manuscript folder by default. This adequately conveys the read-only, high-level behavior, though it does not mention any potential performance implications.

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

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

The description is front-loaded with a clear summary and well-organized Args/Returns sections. However, it slightly repeats return information ('Returns chapter titles...' and 'Returns: Structured overview...'), making it a bit redundant while still 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?

For a tool with one optional parameter and an output schema, the description is complete: it explains what it does, what it returns, the default scan scope, and how it relates to deeper-dive tools. The output schema covers return details, so no further return documentation is needed.

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 compensates by explaining folder_path is optional, giving an example ('Book One'), and stating the default behavior (scans the entire Draft/Manuscript folder). This adds essential meaning beyond the bare 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 the tool scans the project and returns a structured overview with chapter titles, word counts, synopses, and opening lines. It explicitly contrasts with read_document/read_chapter for diving deeper, distinguishing it from sibling tools.

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 usage context: 'Use this to get a bird's eye view, then use read_document or read_chapter(chapter="...") to dive deeper into specific sections.' It names alternatives but does not explicitly state when not to use the tool, so it lacks the explicit exclusion present in a 5.

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?

Since no annotations are provided, the description carries the full burden for behavioral disclosure. It mentions the return format ('List of matching documents with excerpts'), which is useful, but it does not disclose potential side effects, performance implications, authentication requirements, or regex flavor details. This is adequate but leaves gaps.

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, with a one-line summary followed by Args and Returns sections. Every sentence adds value, and the formatting makes it easy to parse. No unnecessary words 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?

The tool is simple with only two parameters, and the description covers the core behavior, scope, and return format. It does not mention edge cases or limitations (e.g., supported file types, performance on large projects), but given the tool's simplicity and presence of an output schema, it is largely complete.

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%, so the description must compensate. It adds meaningful semantics beyond the schema: 'query' is described as 'Text or regex pattern', clarifying regex support, and 'case_sensitive' is explained with its default. This goes beyond what the bare schema provides.

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 ('Search for text') and the resource ('all documents in the project'), which makes the tool's purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'scan_project', so it lacks explicit sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only states what it does and does not mention any exclusions or recommended use cases. The scope 'across all documents' implies a general use case, but no explicit decision-making help is offered.

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 present, so the description carries the full burden. It explicitly discloses important behaviors: overwrites existing synopsis, no snapshot taken, project must be closed, and returns a confirmation or error. This goes beyond minimal expectations and gives the agent full awareness of side effects.

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

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

The description is concise and well-structured. It front-loads the purpose, then lists prerequisites, side effects, args, and return value in a compact format. Every sentence adds value, no fluff 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 two-parameter write tool, the description is complete. It covers the operation, prerequisites, side effects, parameters, and return value. It does not rely on an output schema or annotations, yet the agent has everything needed to invoke 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 description coverage is 0%, and the description clearly compensates by defining each parameter: 'identifier: Document title, path, or UUID' and 'synopsis: The synopsis text to write.' This fully explains what each parameter means, far exceeding the bare 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 opens with a specific verb and resource: 'Write the synopsis (index card text) for a document.' It clearly distinguishes itself from sibling read-only tools like get_synopsis by explicitly stating it writes/overwrites, and the return type is a confirmation message.

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 a clear, critical usage condition: 'The project must be CLOSED in Scrivener, otherwise this fails.' This gives the agent crucial context on when it can be invoked. It does not explicitly mention alternatives, but the write-vs-read distinction is implied by the tool name and sibling list, so a 4 is appropriate.

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