Server Quality Checklist

Tool Scores

• org_list_filesC
  2.9/5.0
  Behavior2/5

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

  With no annotations at all, the description carries the full burden of conveying safety and behavior. The verb 'list' strongly implies a read-only operation, but the description does not explicitly say it doesn't modify state or require special permissions, and it doesn't hint at whether the return is a simple name list or a richer structure. Since there are no annotations, this is a notable gap for a tool that may be expected to be side-effect free.

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

  Conciseness4/5

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

  The description is a single, clear sentence with no filler words. It front-loads the action, resource, and scope. It could be slightly more informative, but it earns its place as a concise and well-structured line.

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

  Completeness2/5

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

  The tool is simple, but it has no output schema, so the description should indicate what the return value looks like (file names, paths, etc.). It doesn't, and it also does not mention the default behavior of include_archive or what 'currently tracked' refers to. These are gaps an agent needs to call the tool correctly, making it incomplete despite low complexity.

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

  Parameters3/5

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

  The only parameter, include_archive, has a complete description in the input schema (schema coverage is 100%). The description doesn't add any extra nuance beyond the schema, but also doesn't need to since the schema is sufficient. Baseline of 3 is appropriate here.

  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 what tool does: 'List the org files currently tracked in the org data directory.' It names a specific resource (org files) and location (org data directory), which helps distinguish it from siblings like org_list_todos or org_agenda. However, it doesn't explicitly name a sibling or call out what it is not, so it misses the highest level of distinction.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool instead of alternatives. It neither explains what kind of listing this returns (e.g., file names vs full paths) nor mentions whether the agent should consider modular or filtering options such as the include_archive parameter. The description also doesn't indicate scenarios where a sibling like org_read_file or org_list_todos would be more appropriate.

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

• org_add_noteA
  3.5/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. It states the action (append) and the nature of the note (timestamped), implying mutation. It does not disclose whether it modifies the entry in place, affects timestamps, or requires specific permissions. This is a mutation that could have side effects, so more disclosure would be helpful, but the core behavior is clear.

  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?

  Single sentence, no waste, and the key action (append) is front-loaded. It communicates the action and target efficiently. Could be slightly more descriptive but is appropriately concise.

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

  Completeness4/5

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

  For a simple tool with two fully described parameters and no output schema, the description is nearly sufficient. The main gap is lack of behavioral details (e.g., whether it creates a new line with a timestamp, whether it is reversible). Since it is a simple mutation, the description is close to complete, but omits the timestamp format and the fact that it is an append-to-body operation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both parameters (id and note) are adequately described in the schema. The description adds 'timestamped' and 'append' context but does not go beyond the schema for the parameters themselves. Baseline 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the action (append a note/log line) and the resource (an existing entry). It is distinct from siblings like org_capture which creates new entries anno or org_update_state which changes state. However, it could be more specific about what 'body' means and how this differs from editing the body via other means.

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

  Usage Guidelines3/5

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

  The phrase 'to an existing entry' indicates the tool requires an existing entry, implying it should not be used for new entries (which would use org_capture). Yet it does not explicitly mention when to use this over org_update_state or org_schedule, nor does it warn against using it for initial creation. Clear context but no exclusions.

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

• org_searchA
  3.5/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 burden of behavioral disclosure. 'Search' implies a read-only operation, which is honest, but the description says nothing about the return format, result ordering, size limits, or pagination. For a tool with no output schema and no annotations, these gaps leave an agent guessing what it will get back.

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

  Conciseness5/5

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

  A single sentence with zero filler. The verb, scope, and the three search targets are front-loaded with no redundant phrasing. Every word earns its place.

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

  Completeness3/5

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

  The input side is fully covered by the schema, and the description accurately scopes what is searched. However, with no output schema present and no mention of the result shape, the description is not fully complete — an agent does not know whether the tool returns full entries, IDs, or titles. Adequate but with a clear gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all three parameters (query, tag, include_archive) are already documented with clear semantics. The description adds mild context by establishing what the full-text search covers, which reinforces the query parameter, but it does not materially add meaning beyond the schema — matching the baseline of 3.

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

  Purpose5/5

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

  The description states a specific verb ('search') plus a resource and scope: full-text across headlines, body text, and tags in all org files. This clearly distinguishes it from siblings like org_get_entry (fetch a specific entry) and org_list_todos (list by state) — no other sibling overlaps with full-text search.

  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 conveys when to use it — when you need to find entries by text content, with the tag and include_archive parameters expanding the search. However, it never explicitly names alternatives or states when not to use it (e.g., when you already know the entry ID, use org_get_entry). Usage context is implied but not routed.

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

• org_captureA
  3.9/5.0
  Behavior3/5

  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 states key behaviors: appending to a file, defaulting to inbox.org, and using parent_id for nesting. It does not mention return values, whether the file is created if missing, or what happens on invalid parent_id; these gaps keep it at a minimal-viable 3.

  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?

  Three sentences, each earning its place: the core action, the typical use case, and the two important behaviors (default file and parent nesting). No filler or redundant restatement of the schema.

  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 creation tool with 9 parameters and no output schema, the description plus the fully-covered schema is mostly complete. It explains the default file and nesting, which are the non-obvious behaviors. It could still mention return/error behavior, but the high schema coverage mitigates this 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?

  Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining the default file behavior ('Defaults to file "inbox.org" if none given') and the semantic of parent_id ('nest the new entry under an existing entry instead of appending at top level').

  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 action ('Append a new entry (headline)') and a specific resource ('a local org file'), and it mentions the org-capture style. It does not explicitly differentiate from siblings like org_add_note, though 'new entry' versus note-adding implies a distinction; this keeps it at a 4 rather than a 5.

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

  Usage Guidelines4/5

  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 jot down tasks, notes, or events.' It also explains default behavior and parent nesting, so an agent knows when this tool fits. It does not give explicit when-not-to-use guidance or name alternatives, which stops it from being a 5.

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

• org_archive_entryA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry the full behavioral burden. It clearly describes the core action (moving an entry and its subtree to an archive file) and the intent (keeping a record). However, it does not disclose potential side effects such as whether the operation is reversible, whether permissions are required, or what happens to the original file beyond being removed. These details are missing, so the score is limited to 3.

  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, two sentences, with the primary action and destination front-loaded. It contains no filler or redundancy. Every sentence contributes value, making it well-structured 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 tool with a single parameter, no output schema, and a clear purpose, the description is reasonably complete. It explains the operation and its use case. However, it omits details such as whether the archive file is automatically created if missing, or what the result of the operation is (e.g., no return value). Given the simplicity, this is a minor gap, so a 4 is appropriate.

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

  Parameters3/5

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

  The input schema describes the single parameter 'id' as 'The entry's id.' This provides 100% schema description coverage. The description itself adds no additional meaning about the parameter, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description states a specific verb (move), a precise resource (an entry and its subtree), and the destination (a companion archive file). It also conveys the intent (clean up completed or stale items while keeping a record). This clearly distinguishes it from sibling tools like org_get_entry (read), org_capture (add), or org_update_state (modify state) – archiving is a distinct operation.

  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 states when to use the tool: 'clean up completed or stale items while keeping a record.' This gives a clear context. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, 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.

• org_get_entryA
  4/5.0
  Behavior4/5

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

  'Fetch' clearly signals a non-mutating read operation名家 and 'including its body text' gives useful behavioral detail about the response. It does not cover edge cases like missing ids or permissions, but for a simple single-entry read that is acceptable.

  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 crisp sentence with the key information up front: the verb, the resource, the lookup key, and the main content type returned. No fluff or repetition.

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

  Completeness4/5

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

  For a one-parameter read operation, the description tells the agent what is returned and why id matters. It does not enumerate all possible fields or failure modes, but the tool is simple enough that this is not a major gap.

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

  Parameters3/5

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

  The input schema already documents id thoroughly, including where ids come from. The tool description adds no additional parameter-level meaning, which is fine because no extra detail is needed.

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

  Purpose5/5

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

  The description clearly identifies a specific operation: fetching one entry by its idhol. Mentioning 'full details' and 'body text' distinguishes it from search/list/capture operations.

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

  Usage Guidelines3/5

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

  The description implies when to use it—when an id is already known and full entry content is needed—but it does not explicitly contrast org_get_entry with siblings like org_search or explain when another tool would be more appropriate.

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

• org_list_todosA
  4/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. It discloses default filtering (excludes DONE/CANCELLED), sorting behavior, and optional filters. However, it doesn't mention whether the tool is read-only, whether it returns full entries or summaries, or any side effects. For a listing tool, the disclosed behavior 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 two sentences, front-loads the core purpose, and packs useful details (default exclusions, sorting, optional filters) without waste. 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 read-only listing tool with no output schema and no annotations, the description covers the main behavior: what is listed, default exclusions, sorting, and available filters. It doesn't describe the return format or pagination, but for a simple list tool this is a minor gap. The tool is adequately specified for an agent to call 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%, so the schema already documents all three parameters. The description adds context that filters are optional and that state filtering uses exact TODO keywords, but it doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool lists TODO entries, specifies the default exclusion of DONE/CANCELLED, and mentions sorting by priority then due date. It also distinguishes itself from siblings like org_search and org_agenda by focusing on TODO-like entries across org files.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: to list open TODO entries across files, with optional filters. It doesn't explicitly name alternatives or exclusions, but the context of sibling tools and the phrase 'across all org files' helps an agent understand it's a broad listing tool rather than a search or agenda tool.

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

• org_update_stateA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry full behavioral burden. It does disclose a key side effect: 'Moving into DONE/CANCELLED stamps a CLOSED timestamp; moving out of one clears it.' This goes beyond the basic action. However, it omits other potential behaviors like whether transitions are restricted (e.g., DONE to TODO), reversibility, or return values, leaving some gaps.

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

  Conciseness5/5

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

  Two concise sentences. The first states the primary action and examples; the second immediately covers the important side effect. No filler or redundant information. Front-loaded with the main purpose, making it efficient for an agent to parse.

  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 two-parameter mutation tool with no output schema, the description covers the core purpose, parameter examples, and a key behavioral side effect. It does not explain the return value, but that is not required given no output schema. It could mention transition constraints, but overall it is sufficiently complete for an agent to invoke correctly.

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

  Parameters3/5

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

  The input schema already describes both parameters comprehensively (id and state with enum values and null semantics). The description adds examples of state values and mentions the null removal implicitly, but it does not provide new syntactic details beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate; the description adds minimal extra value.

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

  Purpose5/5

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

  The description clearly states the action: 'Change the TODO keyword of an entry' with concrete examples of states (DONE, TODO, NEXT, WAITING, CANCELLED). It distinguishes this tool from siblings like org_capture (creating) or org_archive_entry (archiving) by focusing on state mutation, making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description implies when to use it (when an entry's TODO state needs changing) and provides context on state transitions via the timestamp behavior. However, it does not explicitly name alternative tools or state conditions for when not to use it, though the sibling set makes the intent clear.

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

• org_read_fileA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It clearly indicates a non-mutating read ('Read', 'exactly as it is on disk') and adds the 'tracked' constraint. It doesn't cover failure modes or output format explicitly, but the raw-read intent makes side effects unlikely and behavior clear.

  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 front-load the core action and value. No filler words, and the second sentence adds one concrete use case rather than repeating implementation 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 one-parameter read-only tool, the description is nearly complete. It explains what it returns semantically ('raw text'), when it is useful, and which context it covers. It lacks explicit error/edge-case notes, but those are likely not necessary for such a simple operation.

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

  Parameters3/5

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

  Schema coverage is 100% and the file parameter already has an example and a pointer to org_list_files. The tool description adds almost nothing beyond the schema for this parameter, so the schema handles the meaning; 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 states a specific verb and resource: 'Read the raw text of one tracked org file, exactly as it is on disk.' It explicitly distinguishes itself from structured tools by mentioning that it surfaces hand-edited content those tools don't, so an agent can tell this from siblings like org_get_entry or org_search.

  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?

  It gives clear context: use this when the user needs their actual file text or hand-edited content not covered by structured tools. It doesn't explicitly name alternatives or provide a when-not-to-use list, but the intended use case is stated well enough for an agent to decide.

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

• org_scheduleA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It clearly explains the two key behavioral nuances: omitting a field leaves it unchanged, while passing null clears it. This is essential for correct invocation and goes beyond a simple 'update' statement, though it doesn't mention side effects or error conditions.

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

  Conciseness5/5

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

  A single, front-loaded sentence that states the action, the target, and the two key behaviors (set/clear) and the omission rule. No fluff; every clause earns its place.

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

  Completeness5/5

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

  For a tool with three parameters (one required) and no output schema, the description covers all necessary call semantics: what the tool does, how to set or clear, and the meaning of omission. An agent can invoke it correctly without needing additional documentation.

  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 each parameter already includes 'or null to clear' in its description. The tool description adds the crucial distinction between omitting a field (leave unchanged) and passing null (clear), which is not in the schema. This adds meaningful semantic value 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 states a specific verb ('set, change, or clear') and a clear resource ('SCHEDULED and/or DEADLINE timestamps on an entry'), making the tool's purpose unambiguous. It distinguishes itself from siblings like org_update_state by focusing on timestamp fields specifically.

  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 used for managing scheduling timestamps but does not explicitly state when to use it versus alternatives, nor does it mention any exclusions. It gives the operation but no guidance on when to prefer this over org_capture or org_update_state.

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

• org_agendaA
  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 key behavioral traits: inclusion of overdue open items when range covers today, default range, and exclusion of unscheduled entries. It does not mention return format or ordering, but for a read-only query tool this is reasonably 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?

  Two sentences, zero waste. The core purpose is front-loaded, followed by the critical exclusion and alternative. 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 query tool with no required parameters and no output schema, the description covers the main behavior, default, and alternative. It lacks a description of the return format, but the inclusion rules and exclusions are clearly specified, making it adequate for an agent to call 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 all parameters already have descriptions. The tool description adds no additional semantic meaning beyond what the schema provides (e.g., no elaboration on date format or include_done behavior). Baseline of 3 is appropriate since the schema does the heavy lifting.

  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 provides an org-agenda style view, specifies the inclusion criteria (scheduled or due within a date range, plus overdue open items when range covers today), and explicitly distinguishes it from org_list_todos by excluding entries without SCHEDULED or DEADLINE. This is a specific verb+resource with clear differentiation.

  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 names the alternative (org_list_todos) and the condition that selects it: entries without SCHEDULED or DEADLINE. Also states the default range (today only), giving the agent clear context for when to invoke this tool versus siblings.

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