Server Quality Checklist

Tool Scores

• list_projectsC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full behavioral burden. It discloses the returned fields but does not mention side effects, ordering, pagination, or any operational constraints. The reference to a format resource adds some context but does not cover these key behaviors.

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

  Conciseness4/5

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

  The description is concise, with two sentences that front-load the primary action and then list return fields. No redundant phrases; it is appropriately sized for a simple tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is relatively simple, and the description covers the main action and return content. However, it omits details like pagination, ordering, or error behavior, which could be relevant, especially since there is no output schema to fill those gaps. The pointer to a format guide helps but is not exhaustive.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% for the single status parameter, which already includes a description and enum. The description's mention of 'optionally filtered by status' mirrors the schema without adding new semantic information, so the added value is minimal.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action (list all projects) and the optional filter (status), and indicates the returned fields (titles, slugs, status, description previews). It implicitly distinguishes from sibling get_project and search_projects by framing this as a broad list, but it does not explicitly name alternatives.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus the sibling search_projects or get_project. The description only states the tool's function, not the conditions for preferring it over alternatives.

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

• diagnostic_envB
  3.4/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'checks' environment variables, implying read-only behavior, but does not describe what the check returns, whether it has side effects, or any permission requirements. This is minimal disclosure.

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

  Conciseness5/5

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

  The description is a single, compact sentence with no filler words. It front-loads the tool's purpose ('Diagnostic tool') and is appropriately sized for the tool's simplicity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool has no parameters and no output schema, the description is mostly complete for calling it. However, it does not describe what the agent should expect in the response (e.g., whether it returns environment variable values, a status, or logs). This missing return-value context is a notable gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool takes zero parameters, so the baseline for this dimension is 4. The description does not need to explain parameter meaning, and the schema coverage is effectively 100% (vacuous). No additional explanation is needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action ('check'), the resource ('environment variables'), and the context ('for ediff approval'). This distinguishes it from the CRUD-oriented sibling tools. However, the term 'ediff approval' is not explained, leaving some ambiguity for an agent unfamiliar with the domain.

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

  Usage Guidelines3/5

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

  The description implies use as a diagnostic tool, but does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or prerequisites. Since it is the only diagnostic tool among siblings, the implied usage is somewhat clear, but explicit guidance is missing.

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

• link_task_to_projectA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a mutation ('Add') but does not indicate whether existing links are preserved or replaced, whether the task is validated, what permissions are needed, or what the success/failure response looks like.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The core action is front-loaded, and the example is placed directly after the action to clarify the required format.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple two-parameter tool with full schema coverage, the description is adequately complete on inputs. However, with no annotations and no output schema, it should say more about the expected side effects or return value, especially since this is a mutating operation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by giving a concrete org-mode link example for task_link, clarifying the expected string format beyond the schema's short description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb and resource: 'Add a task link to a project's Related Tasks section.' This clearly distinguishes the tool from siblings because no other tool mentions linking tasks to projects or Related Tasks. The example org-mode link further reinforces the intended operation.

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

  Usage Guidelines3/5

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

  The description implies the use case: an agent should use this when a task link needs to be added to a project's Related Tasks section. However, it does not explicitly contrast this with alternatives like create_task or update_task, nor does it state any exclusions or prerequisites such as the task needing to exist.

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

• move_taskA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral burden. It discloses a key behavior: content is not modified, which is valuable. However, it does not describe potential side effects, error conditions, or what happens if the from_section does not match the task's current section. The core behavior of moving is clear, but additional transparency would improve the score.

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

  Conciseness5/5

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

  The description is a single sentence that front-loads the action, scope, and an important constraint. Every word is purposeful, with no filler or repetition. It is highly concise while still conveying the essential purpose.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has three required parameters, no annotations, and no output schema, so the description must carry more weight. It does not mention return values, failure modes, or the exact mapping of section names (the example conflicts with the enum values). The description is too sparse to be considered complete for an agent selecting this tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is only 33%, and the description does not compensate. It uses the example 'Active to Completed' but the schema enums are 'Tasks' and 'Completed Tasks', creating potential confusion. It does not explain the meaning of from_section and to_section beyond their names, nor clarify that from_section should reflect the current section and to_section the destination. Description adds little semantic value over the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('move') with a clear resource ('task') and scope ('between sections'), and explicitly excludes content modification, distinguishing it from update_task. The example 'Active to Completed' provides a concrete use case. This fully clarifies what the tool does and how it differs from siblings.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool (moving a task between sections) and the constraint 'without modifying content' implies a distinction from update_task. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a full 5.

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

• get_projectA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It does state the return content ('full project content including all properties and sections') and points to a format spec, which is useful. However, it does not explicitly state that this is a read-only operation, nor does it mention error behavior or side effects, which are gaps given the absence of annotations.

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

  Conciseness5/5

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

  The description is two sentences with no fluff. The first sentence front-loads the core action and accepted identifier types, and the second sentence provides a pointer to format specifications. Every word adds value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the simplicity of the tool (one parameter, no output schema), the description is nearly complete: it states the resource, the identifier types, and what the return contains. The pointer to the project-format guide adds valuable context. It omits potential edge cases like partial title matches, but for a getter tool this is minor.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema covers the single parameter 'identifier' with a description identical to the tool description ('Project slug, CUSTOM_ID, or title substring'). With 100% schema coverage, the baseline is 3, and the tool description merely repeats the schema without adding new meaning or clarifications about format or precedence. No additional semantics beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'Get' against a specific resource 'project' and defines the identifier as slug, CUSTOM_ID, or title substring. It also promises full project content including properties and sections, which distinguishes it from list_projects and search_projects. The purpose is unambiguous.

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

  Usage Guidelines3/5

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

  The description implies this tool is for fetching a specific project by identifier, but it never explicitly contrasts it with sibling tools like list_projects or search_projects. There's no 'use this when you have an identifier, use list to enumerate, use search to filter' guidance. The usage context is inferred but not spelled out.

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

• get_journal_entryA
  4/5.0
  Behavior4/5

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

  There are no annotations, so the description carries the behavioral disclosure burden. It explicitly states the operation is a read ('Get') and that it 'Returns complete entry content', which is useful. It does not disclose error behavior or formatting details, but points to a guide for format specifications.

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

  Conciseness5/5

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

  Two sentences with no filler: the first states the purpose and allowed lookup modes, the second states the return and points to a format guide. Each sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read operation with two fully documented parameters, the description covers what the tool does and what it returns. A pointer to the journal format guide fills the format gap. It could add expected not-found behavior, but the tool is simple enough that the current description is nearly complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents both parameters. The description's mention of 'date and time or headline substring' mostly mirrors the schema's identifier description and adds no new semantic information beyond it.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description states a specific verb and resource: 'Get a specific journal entry'. It clearly identifies lookup criteria ('by date and time or headline substring') and states the return value ('complete entry content'). This differentiates it from search_journal and list_journal_entries, which are for broader retrieval.

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

  Usage Guidelines3/5

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

  The description implies this tool is for retrieving one known entry when the date and identifier are available. However, it does not explicitly say when to use an alternative like search_journal or list_journal_entries, and no when-not-to-use guidance is given.

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

• list_tasksA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal that the tool returns task names, headlines, status, and full content, and references a format guide, but it does not state read-only behavior, limitations, or potential output size implications. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is three purposeful sentences with no filler. It front-loads the core action, then states return fields, then gives usage guidance and a pointer to further format details. Every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple, single-parameter list tool, the description covers purpose, return content, and usage context, and points to a resource for detailed format specifications. It could be slightly stronger by naming sibling tools for alternative use cases, but it is otherwise complete enough for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% and the only parameter, 'section', has a clear enum of 'Tasks' and 'Completed Tasks'. The description adds minimal semantic value beyond the schema, so the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'List all tasks in a section of tasks.org.' It also states exactly what is returned (task names, headlines, status, full content), which clearly identifies the tool's scope and differentiates it from task-specific or search-oriented siblings.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: 'Use this to check for existing tasks before creating new ones, or to get an overview of work in progress.' It does not explicitly mention alternatives like search_tasks or get_task, but the stated use cases are sufficient for an agent to know when this tool is appropriate.

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

• search_projectsA
  4/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the full burden. It discloses the matching behavior (case-insensitive substring) and that it returns projects, which is useful. However, it does not mention any side effects, safety implications, or behavioral constraints such as pagination or limits, leaving some gaps in transparency.

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

  Conciseness5/5

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

  Two brief sentences with no redundant wording. The core purpose is front-loaded, and each sentence adds distinct value: first defines scope and matching, second states return type.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter search tool with no annotations and no output schema, the description is adequately complete. It states what it searches, how it matches, and what it returns. Minor gaps like pagination or result limits are not addressed, but these are not critical for basic usage.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% (the 'query' parameter has a description). The description adds extra semantics by explicitly noting 'case-insensitive substring match', which goes beyond the schema's 'matches titles and content'. This clarifies the exact matching behavior, adding meaningful context.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'search', the resource 'projects', and the scope 'across all projects'. It specifies the matching criteria (case-insensitive substring on titles and section content) and the return type (matching projects). This distinguishes it from sibling search tools like search_tasks and search_journal.

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

  Usage Guidelines3/5

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

  The description implies usage by naming 'all projects', but it does not explicitly provide when-to-use versus alternatives or exclusionary criteria. The sibling tool names give context, but the description itself offers no guidance on when to prefer this over similar searches.

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

• search_tasksA
  4/5.0
  Behavior3/5

  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 the search returns complete matching tasks and works 'across all sections.' However, it omits details like result ordering, pagination, case sensitivity, or any special matching behavior. The added context is useful but limited.

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

  Conciseness5/5

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

  Two sentences, no fluff. The core action is front-loaded, and the usage guidance is compact. Every sentence contributes value, making it easy to parse quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-parameter search tool, the description is sufficient: it states the scope, return behavior, and intended use cases. It lacks details on sorting or limits, but given the simplicity and lack of an output schema, it adequately covers what an agent needs to invoke it correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and the schema already describes the query parameter as 'matches headline and content.' The description adds 'across all sections' scope but doesn't add semantic details beyond the schema. This meets the baseline for full schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Search tasks by query string across all sections.' It specifies the verb, resource, and scope, and distinguishes itself from siblings like get_task (single task) and list_tasks (list all) by focusing on search across sections.

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

  Usage Guidelines4/5

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

  The description gives explicit usage context: 'Use this to check for existing tasks before creating new ones, or to find tasks related to a topic.' This tells the agent when to use it, though it doesn't state when not to use it or explicitly name alternatives beyond the implied comparison with creation tools.

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

• create_journal_entryA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions that it uses the current system time, implies that duplicate checking is the caller's responsibility, and references a format guide. But it doesn't specify any side effects, permissions, or the response format after creation. For a create operation, this is adequate but not comprehensive.

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

  Conciseness4/5

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

  The description is front-loaded with the format and the essential usage guideline (check duplicates first). It packs a lot of useful information into a few sentences without being overly verbose. The common-tags list and format guide reference are concise additions.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a create tool with no output schema, the description covers the key aspects: how to format, what to include, how to avoid duplicates, and where to find more details. It includes practical examples for links and tags. The only minor gap is not explicitly stating the return value, but that is often assumed for create operations. Overall, an agent would be well-equipped to call this tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already offers 100% coverage for all 5 parameters, so the description doesn't need to repeat the basics. It does add value by providing format examples for headline and content (e.g., PR links, task links), which enrich the schema's descriptions. This slightly exceeds the baseline, but since the schema is already thorough, a 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool creates a journal entry and includes the exact format ('** HH:MM [TICKET-ID] headline :tags:'), which distinguishes it from sibling tools like list_journal_entries or update_journal_entry. The verb and resource are specific, and it even provides examples.

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

  Usage Guidelines5/5

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

  It explicitly instructs to check for existing entries using list_journal_entries before creating to avoid duplicates, which is a clear usage guideline relative to siblings. It also directs to the format guide for specifications, giving agents a clear action path.

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

• create_taskA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full behavioral disclosure burden. It discloses that :ID: is auto-generated when omitted, that CREATED and MODIFIED timestamps are managed automatically, and that duplicate search is required. It does not specify the behavior when a duplicate is found or what response the tool returns, but the disclosed behaviors go well beyond a minimal create description.

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

  Conciseness5/5

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

  The description is four sentences, all information-bearing and free of filler. The core action is front-loaded, followed by format requirements, auto-generation behavior, and guardrails. Every sentence earns its place, and the external format-guide reference avoids unnecessary inlining.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a two-parameter create tool with no output schema and no annotations, the description covers required parameters, provides duplicate-search guidance, explains auto-generated fields, and points to a format reference. It does not describe the return value or error cases, but those are not essential for correct invocation given the schema and example already present.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, and the schema already documents both parameters with descriptions and an example. The description adds extra meaning by emphasizing the required PROPERTIES drawer fields, the subsections structure, auto-generation behavior, and a pointer to the format guide. This exceeds the schema-only baseline but does not fully replace schema documentation for every field.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific verb and resource: 'Create a new task in a section.' It goes on to define the required org-formatted entry, which makes the tool's purpose unmistakable. However, it does not name or otherwise differentiate itself from sibling tools such as update_task or move_task, so it does not fully meet the 5-level bar.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: which sections are allowed, the need for a complete org-format entry, and the explicit instruction to always search for duplicates before creating. It does not state when to prefer an alternative tool, nor does it give an explicit when-not-to-use condition, but the guidance provided is sufficient for a straightforward create operation.

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

• search_journalA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full behavioral burden. It discloses that the tool returns complete matching entries and that it searches last 30 days by default. This gives the agent a clear sense of the output and time scope. However, it doesn't mention any limits, pagination, or whether the search is case-insensitive or fuzzy, which are minor gaps for a search tool.

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

  Conciseness4/5

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

  The description is four sentences, front-loading the core purpose and then adding usage guidance and the default window. Every sentence contributes useful information without redundancy. A small improvement would be to combine the default latency into the first sentence, but the current structure is clear and efficient.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple search tool with two parameters and no output schema, the description covers the essential return behavior ('Returns complete matching entries') and the default time range. It doesn't mention potential pagination or result limits, which could be relevant for large queries, but the tool appears straightforward. Overall, the description is sufficiently complete for an agent to invoke it correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, with both query and days_back having descriptive text. The description adds little beyond restating the schema: 'query string' and 'matches headlines and content' align with the schema, and the default 30 days is already in the parameter description. The description's main additional value is in usage context, not parameter semantics, so a baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'search', the resource 'journal entries', and the scope 'across recent days'. It also explicitly notes it returns complete matching entries, which distinguishes it from get_journal_entry (fetches a specific entry) and list_journal_entries (lists without query). The sibling context reinforces differentiation, as search_tasks and search_projects target different resources.

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

  Usage Guidelines4/5

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

  The description provides explicit usage scenarios: 'find past work on a topic, review recent activity, or look up when something was done.' It also mentions the default 30-day window, which sets expectations. However, it doesn't explicitly contrast with alternatives like get_journal_entry or list_journal_entries, though the purpose wording makes the distinction clear.

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

• list_journal_entriesA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. The verbs 'List' and 'Returns' clearly indicate a read-only operation, and the description discloses what content the response includes. It does not mention sorting or pagination, but for this simple list tool, the essential behavior is transparent.

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

  Conciseness5/5

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

  The description is concise and well-structured: the main action and scope are front-loaded, followed by return values, usage intent, and a helpful format-specification pointer. Every sentence contributes meaningful information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with one optional parameter and no output schema, the description provides enough information to use it correctly: what it lists, what it returns, why to use it, and where to find format details. The date default is covered by the schema rather than the description, which is acceptable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The only parameter, date, is fully documented in the input schema with format and default behavior. The description adds no additional parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the operation ('List'), the resource ('journal entries'), and the scope ('for a specific date'), and enumerates what is returned. This makes it easy to distinguish from get_journal_entry, which retrieves a single entry, and search_journal, which implies broader search behavior.

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

  Usage Guidelines4/5

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

  The description explicitly gives a use case: check what is already logged before creating new entries to avoid duplicates. It provides clear context for when to use this tool, though it does not explicitly name alternatives or exclusions beyond that.

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

• create_projectA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description discloses auto-generation of :ID:, :CREATED:, and default :STATUS:, which is beyond the schema. It also indicates the required structure of the input. However, it does not mention side effects, error behavior, or return value, though these are less critical for a create operation.

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

  Conciseness5/5

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

  The description is three sentences with no filler. It front-loads the core action, then details the input requirements, and finally directs to a guide. Every sentence adds value and nothing is redundant.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is simple with one parameter and no output schema. The description covers purpose, input format, and points to a resource for full specifications. It omits return behavior and error handling, but these are not essential for an agent to correctly invoke the tool, given the guide reference.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description substantially enriches the single parameter (project_entry) beyond the schema's one-line definition. It specifies the required structure (level-1 heading, :PROPERTIES: drawer with :CUSTOM_ID:, level-2 sections) and points to a detailed format guide, giving an agent clear guidance on constructing valid input.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb (create) and resource (project file), and clarifies it's from an org-formatted string. It distinguishes itself from siblings by specifying project creation specifically, and mentions auto-generated fields, making the purpose unambiguous.

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

  Usage Guidelines3/5

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

  The description implies use for creating new projects but does not explicitly state when to use this tool over alternatives like create_task or create_journal_entry. It gives no when-not guidance or direct comparisons, leaving the agent to infer from the tool name and context.

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

• get_taskA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses that the operation returns full task content including all properties, subsections, and task items, and points to a format specification guide. It does not discuss error behavior or side effects, but 'Get' implies a read-only operation and the return content is well specified.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The operation and identifier examples are front-loaded, and the return content summary plus format guide pointer are compact and useful.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  There is no output schema, so the description's summary of return content and the pointer to the task-format guide cover the main expectations. It does not specify behavior for ambiguous substring matches, but that is a minor gap given the schema and guide link.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. The tool description adds value above the schema by providing concrete examples of valid identifier formats (#+NAME 'task-gh-28', ticket ID 'GH-28'), which help an agent construct correct inputs. The section parameter is already well documented in the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states the specific verb 'Get' and resource 'specific task,' and defines the identifier formats with concrete examples (#+NAME, ticket ID, headline substring). This clearly distinguishes it from sibling tools like list_tasks or search_tasks, which operate on collections rather than a single known task.

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

  Usage Guidelines4/5

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

  The description clearly indicates the tool is for retrieving a specific task when an identifier is available. It does not explicitly mention alternatives or when not to use it, but the identifier-based operation makes the usage context clear.

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

• regenerate_project_indexA
  4.4/5.0
  Behavior3/5

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

  With no annotations, the description must disclose effects. It implies overwriting the index but does not explicitly state that it will replace the file or that manual edits may be lost. This is a minor gap for a potentially destructive regeneration operation.

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

  Conciseness5/5

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

  One sentence with no filler, front-loading the action and purpose, and immediately stating the usage conditions. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Adequate for a simple parameterless tool with no output schema; covers action and usage conditions. Could mention the outcome (index file updated) but the core information needed to decide when to call it is present.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so there is nothing to document beyond the schema. Baseline of 4 is appropriate since no compensation is needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb 'regenerate' and a specific resource '~/org/projects/index.org' from project files, clearly distinguishing it from sibling CRUD operations like list_projects, get_project, and create_project.

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

  Usage Guidelines5/5

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

  Explicitly provides conditions: 'Call this once after initial setup or if the index becomes out of sync', giving clear when-to-use guidance without needing to reference alternatives.

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

• update_projectA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses meaningful behavioral traits beyond the schema: the automatic :MODIFIED: timestamp update and the section-level write mechanism that avoids full-file rewrites. It does not specify whether properties are merged or replaced, but the key side effects are surfaced.

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

  Conciseness5/5

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

  Four short sentences, each carrying necessary information: the action and scope, the section-level behavior, the required-field invariant, the automatic timestamp, and a pointer to the format guide. There is no filler, repetition, or restatement of the tool name.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the moderate complexity and the absence of an output schema and annotations, the description covers essential operational detail: what can be updated, the required-field constraint, the automatic timestamp side effect, and where to find format specifications. It does not describe return values or error behavior, but those are less critical for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by grouping section+content as a unit and stating the at-least-one requirement across tags, content+section, properties, or headline. This helps the agent understand valid invocation combinations.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Update a project's section content, properties, headline, or tags.' It also clarifies the granularity of the operation ('section-level updates'), which distinguishes it from related tools like create_project and update_task. The purpose is unambiguous.

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

  Usage Guidelines4/5

  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 the tool: updating an existing project's fields, with an explicit recommendation to use section-level updates 'to avoid rewriting the entire file.' It also states the required-field invariant. It does not explicitly name alternative tools for creation or other operations, so it stops short of full exclusion guidance.

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

• update_taskA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and handles it well. It explicitly discloses automatic state transitions (TODO→DONE and DONE→TODO), timestamp updates, section moves, and preservation of key properties, which are exactly the side effects an agent needs to anticipate.

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

  Conciseness4/5

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

  The description is front-loaded with the primary purpose and uses a compact numbered list for automatic behaviors. It is dense but efficient; the reference to the format guide avoids inline bloat while still providing a path to needed details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a two-parameter update tool with no output schema or annotations, the description covers purpose, required input shape, preservation rules, and automatic behavior. It lacks explicit failure/error behavior and does not mention what happens when the identifier does not match an existing task, but it is otherwise well-rounded.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema by specifying preservation requirements and examples of properties to retain, such as :ID:, :CUSTOM_ID:, and :CREATED:, and by requiring the complete task entry rather than a partial update.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific action ('Update an existing task') and resource ('task'), and emphasizes replacing with new content. It implicitly distinguishes itself from create_task and get_task by focusing on existing entries and full replacement semantics.

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

  Usage Guidelines4/5

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

  The description gives clear operational context: provide the complete new entry, preserve properties, and follow the format guide. It does not explicitly name alternatives or exclusions, but the focus on 'existing task' makes the intended use reasonably distinct from creation or retrieval.

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

• update_journal_entryA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description must disclose behavioral traits. It reveals that the tool finds by time, uses existing_headline to disambiguate, and replaces content/tags (e.g., 'Updated tags (replaces existing)'). It also points to a format guide for further specs. While it doesn't detail side effects like whether other fields are overwritten, the disambiguation and replacement behavior is genuinely informative.

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

  Conciseness5/5

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

  The description is compact: three sentences that state what it does, how it finds the entry, and when to use it. The disambiguation note is front-loaded and the format pointer is a useful addition without bloat.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and no output schema, the description handles the essential behavior (lookup, disambiguation, replacement) and routes to a format guide. It doesn't state what the return value is or whether the update is destructive to unspecified fields, but it covers the core operation thoroughly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the lookup mechanism (time + existing_headline) and clarifying that tags replace existing, which is valuable. However, it doesn't explain the relationship between time/existing_time fully beyond the schema defaults, but the schema description covers most.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description explicitly states the verb ('Update'), the resource ('existing journal entry'), and the mechanism (find by time, with existing_headline for disambiguation). It distinguishes itself from create_journal_entry and search_journal by focusing on updating existing entries and adding details, which is clear from the sibling list.

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

  Usage Guidelines5/5

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

  The description includes explicit guidance on when to use this tool: 'Use this to correct or enhance existing entries, or add forgotten details like task links.' It also implicitly excludes creation by saying 'existing journal entry' and provides a disambiguation strategy. However, it does not explicitly mention alternatives like create_journal_entry, but the use-case guidance is strong enough to route the agent correctly.

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