AIMFP

by aryanduntley

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.37.0
Disambiguation3/5
Many tools have similar purposes (e.g., various add and get functions for items, tasks, subtasks, sidequests) and the large number creates potential confusion. However, detailed descriptions help distinguish them, and each tool has a specific role.
Naming Consistency5/5
Tool names consistently follow a verb_noun pattern (e.g., add_item, get_task, delete_file, update_module). Even orchestrators like aimfp_init and get_git_status follow a recognizable naming convention. No mixing of styles.
Tool Count1/5
With 253 tools, the server is extremely large for an MCP server. Most well-designed servers have under 20 tools. This count suggests over-engineering and would overwhelm any agent attempting to choose the right tool.
Completeness5/5
The tool set covers an exhaustive set of operations for the domain: CRUD, batch operations, search, state management, initialization, and orchestration. There are no obvious gaps for the tracked entities (files, functions, types, modules, tasks, directives, etc.).
Average 3.6/5 across 253 of 253 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 11 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's 'Delete interaction' adds no new behavioral context. There is no mention of cascading deletes, reversibility, permissions, or side effects beyond the deletion itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While very concise (2 words), the description is under-specified and fails to provide essential information. Structure is non-existent. Conciseness without utility is not beneficial.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature (destructiveHint=true) and 5 required parameters, the description is severely lacking. It does not explain what an interaction is, what the consequences of deletion are, or how to appropriately use the note parameters. No output schema means more burden on description, which it fails to meet.
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 100% with clear descriptions for all 5 parameters. The description 'Delete interaction' adds no additional meaning to any parameter. Baseline is 3 for high coverage, but the description contributes no value, resulting in a 2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete interaction' is a tautology of the tool name 'delete_interaction'. It does not differentiate what an 'interaction' is from other deletable entities like files, flows, or tasks. Among many sibling delete tools, no distinction is provided.
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 usage guidance is given. There is no indication of when to use this tool instead of alternatives, no prerequisites (e.g., needing an interaction ID from a get function), and no warnings about consequences. Sibling tools like get_interactions_by_file could provide context but are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and non-destructive behavior. The description adds no additional behavioral context (e.g., whether updates are partial or full replacement, or any side effects). Thus it adds no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (four words), which might seem concise, but it is under-specified and fails to convey essential usage details. It sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, multiple siblings, and no output schema, the description is extremely incomplete. It does not explain return values, side effects, or how it interacts with other completion path tools. The annotations provide some safety context, but the description fails to fill the gaps.
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%, with each parameter described with its type and role (e.g., 'New name (NULL = don't update)'). The description does not add any extra semantic information beyond what the schema provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update completion path' is a minimal statement of action and resource, but it does not distinguish this tool from many other update tools among siblings (e.g., update_task, update_milestone). It lacks specificity on what aspects of the completion path can be updated, bordering on a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like add_completion_path or other update tools. There are no context signals, prerequisites, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already imply (non-read-only, non-destructive). It does not disclose whether duplicate names are allowed, what side effects occur, or any 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it is under-specified and fails to convey meaningful information. While concise, it does not earn its place due to lack of substance.
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?
Given the tool has 4 parameters, no output schema, and minimal annotations, the description is severely lacking. It explains neither the purpose of a theme nor the effect of adding one, leaving the agent without sufficient context for correct use.
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 baseline is 3. The description contributes no additional context about parameters beyond the schema's existing descriptions, but does not contradict them either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Add project theme' merely restates the tool name with 'project' added. It lacks any explanation of what a 'theme' represents or how it differs from other add resources. Siblings like add_task, add_module, add_note are not differentiated.
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 provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it relates to sibling tools like update_theme or delete_theme.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint, indicating a safe, idempotent operation. The description adds no behavioral context beyond this, such as what happens if the sidequest does not exist, whether the results are paginated, or if there is any ordering. Given annotations already cover the safety profile, a score of 2 reflects minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is concise (one sentence), it is under-specified and lacks structure. Every sentence should earn its place, but this sentence merely restates the name without adding value, making it more of a tautology than a helpful description.
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?
Given the tool has 2 parameters, no output schema, and annotations, the description is incomplete. It does not explain what 'items' are returned, the format, or any constraints. For a retrieval tool, this is insufficient for an agent to fully understand the behavior without further inference.
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% with descriptions for both parameters ('Sidequest ID' and 'pending', 'in_progress', 'completed' (NULL = all)). The description does not elaborate on parameter usage or provide any additional meaning, so the baseline of 3 is appropriate since the schema already sufficiently documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get items for sidequest' is a tautology of the tool's name 'get_items_for_sidequest', restating the exact verb and resource without adding any additional meaning or differentiation from sibling tools like 'get_items_for_subtask' or 'get_items_for_task'.
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?
The description provides no guidance on when to use this tool versus alternatives, no context about prerequisites, limitations, or exclusions. For example, it does not mention that this tool retrieves all items for a sidequest regardless of status, while other tools might filter or return incomplete items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's burden is lower. However, the description adds no behavioral traits like return format or filtering behavior, leaving 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At three words, it is concise but insufficiently informative. The description is under-specified and does not earn its place by providing necessary detail.
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?
Given the complexity (6 parameters, no output schema) and many sibling tools, the description is too sparse. It lacks completeness for an AI agent to use effectively.
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% with descriptions for all 6 parameters. The description does not add new meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Advanced subtask search' is vague and does not specify what the tool returns or its scope. It fails to distinguish from siblings like 'get_subtasks_by_task' which are more specific.
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 on when to use this tool versus alternatives such as 'get_subtasks_by_task' or 'get_incomplete_subtasks'. The description does not mention context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds the claim of 'smart' and 'automatic routing' without explaining what these mean. No details are given about side effects, cascading behavior, or what the routing entails, offering minimal behavioral disclosure beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence, 10 words) but lacks key information. It is not front-loaded with the resource or core purpose, sacrificing clarity for brevity. Every sentence should earn its place; this one is too vague to be effective.
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?
Given the large set of sibling delete tools and the absence of an output schema, the description is incomplete. It does not explain return values, the effect of the six required parameters (including note fields), or elaborate on the 'automatic routing' claim. The tool's complexity demands more context.
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% with all parameters described. The description does not add any additional meaning beyond the schema; it does not explain how parameters influence the 'smart' behavior or routing. Baseline 3 is appropriate as the description adds no value but does not mislead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description says 'Smart delete with automatic routing' but fails to explicitly state what resource is being deleted. The resource 'project entry' is only indicated in the tool name and title, which are separate from the description. This vagueness makes it unclear what the tool operates on.
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 provided on when to use this tool over the many sibling delete tools (e.g., delete_file, delete_flow). The description neither states when it is appropriate nor mentions any alternatives, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, meaning it is a write operation, but the description adds no further behavioral details. It does not disclose side effects (e.g., does it automatically reorder stages?), required permissions, or what exactly 'adding' entails beyond creating a record.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly concise (4 words). While it avoids verbosity, it sacrifices clarity and completeness. It is under-specified for a tool with multiple parameters and siblings.
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?
With no output schema and a minimal description, the tool lacks context about the completion path system, how stages relate to each other, and what happens after adding a stage. It is incomplete for a mutation tool with required parameters.
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%, so the schema already documents all parameters with descriptions. The description does not add any additional meaning or clarify parameter relationships beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('add') and the resource ('completion path stage'), but it is extremely brief and does not clarify what a completion path stage is or how it differs from similar entities like flows or milestones. It is minimally sufficient but lacks specificity to distinguish 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., add_flow, add_milestone, update_completion_path). There are no usage contexts, prerequisites, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false, etc.) are all false, but the description does not disclose any behavioral traits beyond the name. It does not explain whether finalizing is a permanent commit, whether it can be undone, or what side effects occur. The description adds minimal value beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (6 words in one sentence). While it is front-loaded with the key action, it lacks necessary detail. Conciseness is good, but the text is under-specified rather than optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of a likely 'reserve then finalize' workflow, but the description does not mention this context. There is no output schema and no explanation of return values, success indicators, or error conditions. The cryptic 'skip_id_naming?' parameter is left unexplained. The description is severely incomplete for a tool that modifies state.
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 parameter 'types' already has a detailed schema description. The tool description does not add any additional meaning or usage context for the parameters, such as explaining the purpose of 'skip_id_naming?'. Baseline score of 3 applies 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Finalize multiple reserved types', clearly indicating the verb (finalize) and resource (multiple reserved types). However, it does not elaborate on what 'finalize' means in this context, nor does it distinguish from the sibling 'finalize_type' (singular) beyond plurality. A more explicit explanation would improve clarity.
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?
The description provides no guidance on when to use this tool versus alternatives like 'finalize_type' or 'reserve_types'. There is no mention of prerequisites, typical usage flow, or scenarios where this tool should be avoided. The sibling list includes many related operations, but the description offers no differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe, non-destructive read operation. The description adds no behavioral details beyond the annotations, such as pagination behavior, result set characteristics, or performance implications. Therefore, it provides minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise, but it is too vague to be informative. It lacks structure and does not front-load critical details. Every word should earn its place, but here the sentence is generic.
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?
Given the presence of multiple sibling tools, 6 parameters, and no output schema, the description is insufficient. It does not explain the return format, filtering behavior, or how this tool fits among alternatives. It leaves significant gaps for effective agent use.
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 covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description ('multiple filters') does not add new meaning beyond what the schema already provides. No parameters are elaborated further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Advanced task search with multiple filters' indicates the tool searches tasks with filters, but it lacks specificity about the resource (tasks) and does not distinguish it from sibling tools like get_tasks_by_milestone or get_incomplete_tasks. The verb 'search' is present, but the purpose is not sharply defined.
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 provided on when to use this tool versus alternative task retrieval tools such as get_tasks_by_milestone or get_incomplete_tasks. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds no additional behavioral context, such as side effects, validation of definition_json, or what happens if the type_id does not exist.
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 short sentence, which is efficient and front-loaded. However, it could include slightly more detail without becoming verbose.
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?
No output schema, so the description should hint at the return value (e.g., success confirmation or updated type object). Lacks context on partial update behavior and error handling.
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 has 100% coverage with clear parameter descriptions (e.g., 'New name (NULL = don't update)'). The tool description adds no further meaning; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes the action as 'Update type metadata', which is a verb+resource, but 'type' and 'metadata' are vague and do not differentiate from other update tools like update_file or update_function. It could be more specific about what kind of type (e.g., custom types).
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 on when to use this tool versus alternatives such as update_file or update_module. Does not specify prerequisites, contexts, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe, read-only operation. The description adds no additional behavioral context beyond what annotations provide. It does not contradict annotations, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise but lacking substance. It could be expanded to include more useful information without becoming verbose. It is not overly long, but it is too minimal for optimal clarity.
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?
Given the tool has 4 parameters including nested objects, and no output schema, the description should clarify behavior like return format, pagination, or limitations. It does not address these aspects, leaving the agent with incomplete information for reliable 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%, so each parameter is documented. The description's phrase 'structured JSON conditions' adds minimal context about the 'conditions' parameter but does not provide additional semantic meaning beyond the schema's 'Field-value pairs (AND logic)'. The description does not compensate beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Flexible filtering with structured JSON conditions' gives a general sense of the tool's purpose but is vague. It indicates filtering and JSON conditions but does not explicitly state it retrieves data from a project table. The tool name suggests the domain, but the description lacks specificity.
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 provided on when to use this tool versus alternatives like 'get_from_project' or other query tools. The description does not mention context, prerequisites, or scenarios where this tool is appropriate, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, but the description does not explain partial update behavior (NULL fields not updated) or any side effects. It adds no behavioral context beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, front-loaded but too vague. It could be more specific without becoming verbose, but it is not overly long.
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?
Given 5 parameters (including nested objects) and no output schema, the description is insufficient. It does not explain the update semantics (e.g., nullable fields mean no update), which is critical for correct usage.
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%, so each parameter has a description. The tool description adds no additional semantics or examples. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update function metadata' uses a specific verb and resource, but 'metadata' is vague. It does not differentiate from siblings like update_function_file_location or finalize_function, which have more specific scopes. The schema clarifies parameters but the description itself lacks precision.
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?
The description provides no guidance on when to use this tool versus alternatives such as update_function_file_location (for location changes) or finalize_function (for finalization). It does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so the description adds no extra behavioral context. It does not clarify what happens to existing fields when only some are updated, or any side effects beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence, three words) but omits important details like which fields can be updated. Concise should not come at the cost of completeness; a more informative one-sentence description would be better.
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?
Given 9 parameters, no output schema, and many sibling tools, the description is insufficient. It does not mention that 'id' is required, that other fields are optional, or what the return value is (e.g., the updated note).
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 has 100% description coverage for all 9 parameters. The description adds no additional meaning beyond the schema, but the baseline score is 3 because schema already documents each 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 'Update note metadata' clearly states the verb 'update' and resource 'note', distinguishing it from sibling tools like add_note, delete_note, and get_notes. However, 'metadata' is slightly misleading because the schema includes 'content' which is the note body, not just metadata.
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?
The description provides no guidance on when to use this tool versus alternatives such as add_note (create new note) or search_notes. It does not mention any prerequisites or context for updating a note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, so safety profile is clear. Description adds no behavioral detail beyond 'update' (e.g., partial vs full update, response). No contradictions, but minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (3 words) but lacks structure. No details like parameter usage or return values. Could be expanded without sacrificing brevity.
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?
With 3 required params, no output schema, and nested objects, description is too brief. Does not explain valid tables, effect on existing fields, or what 'entry' means. Incomplete for a generic update tool.
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 covers all 3 parameters with descriptions. Description adds no additional meaning beyond what schema provides. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Update existing entry' includes verb+resource but is generic. Does not distinguish between many sibling update tools for specific entities (e.g., update_file, update_flow). The name and schema indicate it updates a project entry in a given table, but description lacks that specificity.
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 on when to use this tool vs alternatives. With many sibling update tools, agent needs context about which table or entry type this applies to. No when-not or exclusion advice provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true, indicating a safe read operation. The description adds no new behavioral traits such as permissions, side effects, or return format, providing minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no extra words. It is concise but lacks additional structure or detail that could aid understanding.
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 retrieval tool with one parameter and no output schema, the description is minimally adequate. However, it does not specify what the response contains (e.g., file objects or IDs), which would improve completeness.
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?
The schema describes the single parameter 'flow_id' as 'Flow ID' with 100% coverage. The description does not elaborate on the parameter's meaning, format, or how to obtain a valid flow_id, adding no extra semantic value.
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 'Get all files for a flow' clearly states the verb (get) and resource (files for a flow). It is direct and understandable, but does not differentiate from sibling tools like get_file_by_name or get_files_by_flow_context.
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 provided on when to use this tool versus alternatives. Sibling tools include multiple file-retrieval functions, but the description lacks any context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description repeats the constraint about empty arrays, which is already in the schema. It adds minimal behavioral information beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and concise, but it sacrifices completeness. The bold emphasis on empty arrays is useful but largely repeats schema content.
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?
With no output schema, the description should clarify return values or result format. It does not, and also fails to specify what 'records' entails, leaving the agent without enough context for complete understanding.
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%, so the description has little burden. It adds no new meaning beyond the schema descriptions, which already document the parameters.
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 'Get records by ID(s)' clearly states the verb (get) and resource (records from settings), distinguishing it from sibling tools like get_from_settings_which includes a WHERE clause.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_from_settings_where or other get tools. The description lacks context on usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true. Description adds 'directive-callable' qualifier, which provides slight behavioral context beyond annotations. However, no additional traits (e.g., scope, side effects) are disclosed.
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 wasted words, front-loaded. However, given the simplicity, adding a clarifying phrase about the tool's specific scope would not harm conciseness.
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?
Despite no parameters and annotations, the description is too minimal for a tool with many siblings. The lack of output schema and omission of filtering logic means the agent may not understand what 'helpers' are or how this differs from similar tools. More context is needed.
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?
No parameters exist, and schema coverage is 100%. Baseline is 3 as per scoring guidelines. Description adds no parameter information, which is acceptable given no params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states verb and resource ('Get all directive-callable helpers') but fails to clarify the distinction from siblings like 'get_helpers_are_tool' or 'get_helpers_are_sub'. The name implies a filter, but the description does not mention it, making the purpose only moderately clear.
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 on when to use this tool versus alternatives. With many sibling get_helpers_* tools, explicit context about selecting this specific variant is missing, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds no additional behavioral context. It does not describe what happens with missing filters, pagination, or performance implications, leaving the agent without useful operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words) but lacks substantive content. It is not front-loaded with key information; a minimal viable description would at least state the purpose clearly.
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?
Given the tool has 7 parameters and no output schema, the description is too brief to fully inform an agent. It does not explain the scope of search, relationship to sibling tools, or behavior when parameters are omitted.
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 parameters with descriptions. The description adds no extra meaning beyond 'Advanced sidequest search'. Baseline of 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 'Advanced sidequest search' clearly indicates this tool retrieves sidequests with advanced filtering. The name 'get_sidequests_comprehensive' reinforces that it fetches sidequests comprehensively, distinguishing it from siblings like 'get_sidequest_files' or 'get_incomplete_sidequests'.
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 explicit guidance on when to use this tool versus alternatives such as 'get_incomplete_sidequests' or 'get_sidequest_files'. The description does not mention prerequisites, exclusions, or scenarios where other tools 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds that files are retrieved 'via flows (orchestrator)', which hints at the mechanism but does not explain behavior beyond what annotations cover. There is no mention of permissions, limitations, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single sentence. However, it lacks structure and does not front-load key information. It is minimally adequate but not well-organized.
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?
Given the tool has a simple input schema (one parameter), no output schema, and annotations covering read/idempotent, the description is incomplete. It fails to explain what constitutes 'files related to a task', what 'via flows' means operationally, or what the return format is. The absence of output schema places a burden on the description to describe the output, which is unmet.
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%; the only parameter 'task_id' is described as 'Task ID' in the schema. The description does not add any additional meaning or clarity to the parameter beyond what the schema already provides.
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 purpose: getting all files related to a task via flows (orchestrator). The verb 'Get' and resource 'files related to task' are specific. However, the phrase 'via flows (orchestrator)' is ambiguous and could be more precise. Among siblings, it distinguishes itself from similar tools like get_sidequest_files and get_files_by_flow.
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 usage guidelines are provided. The description does not mention when to use this tool versus alternatives like get_sidequest_files or get_files_by_flow. There is no guidance on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral context, such as whether the update is partial or full, whether it requires file ownership, or what happens on failure. It fails to add value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words), which is both a strength and a weakness. It is front-loaded and easy to parse, but it lacks substantive detail that could help the agent understand the tool's behavior without looking at other fields.
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?
Given the tool has 4 parameters, annotations, and no output schema, the description is insufficient. It does not explain the outcome (e.g., returns updated metadata, success status), nor does it summarize the key semantic rules (e.g., only non-null fields are updated). The agent is left to rely solely on the schema for understanding.
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%, with each parameter having a description. The tool description does not add any extra meaning beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update file metadata' clearly states the verb (update) and resource (file metadata). It distinguishes from sibling tools like delete_file or finalize_file, but could be more specific about which metadata fields are affected (though the schema lists them).
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 provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or when not to use it. The agent must infer usage from the name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, but the description adds no supplementary behavioral details. It does not disclose whether moving a function affects references, requires permissions, or has side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (five words), which is concise but lacks structure. Every word earns its place, but the brevity omits important information. A longer, more structured description would improve usability without being wasteful.
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?
Given the tool's three parameters and no output schema, the description is too sparse. It does not explain the effect of moving a function, potential constraints, or what happens to related objects. More context is needed for effective use, especially given the complex domain and many sibling tools.
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 covers all three parameters with clear descriptions, achieving 100% coverage. The tool description adds minimal meaning beyond the schema, simply restating the action. Baseline 3 is appropriate as the schema already provides adequate semantics.
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 verb 'Move' and the resource 'function to different file', distinguishing it from sibling tools like update_function or update_file. The 'rarely used' qualifier adds context, though it does not elaborate on the scope or impact of the move.
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?
The description only notes that the tool is 'rarely used', but provides no explicit guidance on when to use this tool versus alternatives, such as update_function or when to move functions vs. other operations. No when-not-to-use or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds no further behavioral context, such as confirmation requirements, side effects, or the fact that it only updates specified fields while leaving others unchanged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At three words, the description is very concise but does not provide sufficient context for a tool with 4 parameters. It avoids fluff but sacrifices informativeness.
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 description lacks details on success/failure behavior, potential constraints (e.g., cannot update theme_id), or any return information. Given the complexity of update operations and lack of output schema, it is incomplete.
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% with descriptive parameter descriptions (e.g., 'NULL = don't update'). The description does not add any meaning beyond the schema, meeting the baseline of 3.
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 'Update theme metadata' clearly indicates a verb-resource pair, and combined with the parameter names (name, description, confidence_score), it specifies what is updated. It distinguishes from siblings like add_theme (create) and delete_theme (remove).
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?
The description provides no guidance on when to use this tool versus alternatives like add_theme, delete_theme, or other update tools. No context about prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no additional behavioral details, such as whether changes are immediately persisted, if authorization is required, or if the tool creates a default flow with other fields.
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 extremely concise at three words, with no wasted text. However, it may be too terse for a tool with four parameters; a slightly more informative description could be provided without sacrificing brevity.
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?
Given no output schema and moderate complexity (4 parameters, 2 required), the description fails to explain what the tool returns (e.g., the created flow object) or side effects like duplicate handling. Context from sibling tools suggests flows are used in a broader system, but this is not referenced.
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 has 100% description coverage, so each parameter already has a clear description. The tool description does not add any new semantic context for the parameters, making it adequate but not enhancing understanding.
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 'Add project flow' clearly states the verb 'Add' and the resource 'project flow', indicating creation of a new flow. It distinguishes from sibling tools like 'add_file_to_flow' which add a file to an existing flow. However, it does not elaborate on what a flow represents, which might be understood from context.
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 provided on when to use this tool versus alternatives such as 'update_flow' or 'get_all_flows'. There is no mention of prerequisites like unique naming, required project context, or constraints on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a mutable operation (readOnlyHint=false), but the description adds no further behavioral context such as side effects, permissions, or idempotency. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point, containing one sentence with no wasted words. It could be expanded but is not overly verbose.
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?
Despite full schema coverage, the tool has a nested 'data' object parameter and no output schema. The description does not clarify acceptable table names or the structure of field-value pairs, leaving gaps for a complex mutation tool.
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% so the baseline is 3. The description 'project database' implies the 'table' parameter refers to project tables, but it adds no specific meaning beyond the schema.
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 'Add new entry to project database' clearly indicates what the tool does with a specific verb and resource, distinguishing it from more specific siblings like 'add_settings_entry' or 'add_user_custom_entry'.
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 alternatives. With many sibling tools like 'add_item' and 'add_note', the description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal info (not read-only, not destructive). The description adds no behavioral details beyond the action. It does not disclose side effects, authorization needs, rate limits, or error behavior. For a mutation tool with sparse annotations, more transparency is needed.
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 sentence with no wasted words. It is concise and directly states the purpose. However, it lacks structure (e.g., sections, bullet points) and is not front-loaded with key info beyond the initial verb. Still, every word earns its place.
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?
Given the tool has 7 parameters, 2 required, no output schema, and sparse annotations, the description is insufficient. It does not explain return values, error behavior, or provide complete context for an agent to use it effectively without additional knowledge.
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% (all 7 parameters have schema descriptions). The description does not add any additional meaning beyond what the schema provides. Baseline score of 3 is appropriate as the schema already defines parameters adequately.
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 tool adds a note to the user_directives.db notes table for AI record-keeping. The verb 'Add' and resource 'note' are specific. However, it does not differentiate itself from sibling tools like 'add_note' or 'add_tracking_note', which are generic.
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 on when to use this tool vs alternatives. It only mentions 'for AI record-keeping', which is vague. No exclusions, prerequisites, or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-idempotent behavior. The description adds 'with status validation' but does not explain what validation occurs, what happens on failure, or any side effects like cascading deletions. It adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no wasted words. It is appropriately sized and front-loaded.
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?
For a destructive tool with 5 required parameters and no output schema, the description lacks detail on the validation process, expected outcomes, and permissions. It is inadequate for an agent to fully understand the tool's behavior.
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% with clear descriptions for all 5 parameters. The description does not add any additional meaning or context beyond what the schema provides, so baseline score applies.
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 verb 'delete' and resource 'item', and mentions 'status validation' as a qualifier. It distinguishes from siblings like 'delete_file' by targeting 'item', but doesn't define what an 'item' is relative to other entities like tasks or subtasks.
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 provided on when to use this tool versus the many sibling delete tools (e.g., delete_task, delete_subtask). The description does not mention alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds minimal behavioral insight. It does not disclose what is affected (e.g., whether the relationship removal cascades or if it deletes related records).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (3 words), which is efficient but lacks any additional context that might be helpful, such as what the relationship entails.
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 deletion tool with annotations covering destructiveness, the description is minimally adequate but could mention that it deletes a junction table entry without affecting the type or function entities.
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%, so each parameter is documented. The description does not add extra 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Remove type-function relationship' clearly states the verb ('Remove') and the specific resource ('type-function relationship'), distinguishing it from sibling delete tools like 'delete_type' or 'delete_function'.
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 on when to use this tool vs alternatives (e.g., 'delete_type', 'delete_function', 'update_type_function_role'). Missing context about prerequisites or when removal is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds no additional behavioral context (e.g., behavior on missing directive, multiple targets). With annotations covering the core traits, a 3 is appropriate.
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, directly to the point, with no unnecessary words. Ideal conciseness.
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?
Tool returns a value (likely a string or object) but no output schema exists and the description doesn't hint at the return format. For a retrieval tool, this is a significant gap. Also, no prerequisites or side effects are mentioned.
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 covers the single parameter with description 'Directive name' (100% coverage). The tool description adds no further meaning beyond what the schema states, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get where to loop back after completing directive' states a specific verb and resource but is vague. It doesn't differentiate from siblings like 'get_next_completion_path' or 'get_completion_paths_by_status', which also deal with completion targets.
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 on when to use this tool versus alternatives. For example, it doesn't clarify when to prefer this over 'get_next_completion_path' or 'get_incomplete_completion_paths'. The description lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds no additional behavioral context, but the annotations cover the main safety profile adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short single phrase, which is concise but could benefit from a bit more detail without becoming verbose. It front-loads 'flexible filtering' appropriately.
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?
No output schema and the description does not explain what is returned. Given the complexity of filtering, the absence of return value specification is a significant 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?
Input schema has 100% coverage with descriptions for both parameters. The description's 'structured JSON conditions' adds minimal nuance beyond the schema's 'Field-value pairs (AND logic)'.
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 name 'get_from_settings_where' and description 'Flexible filtering with structured JSON conditions' clearly indicate the tool retrieves settings records with filtering. It distinguishes from sibling 'get_from_settings' which likely returns all settings.
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 on when to use this tool vs alternatives like 'get_from_settings'. No mention of when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe. The description adds no additional behavioral context beyond the basic retrieval, which is sufficient given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence of 6 words with no redundancy. It is maximally concise and appropriately front-loaded.
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?
Despite having no parameters, the description does not explain the output format or return structure. With no output schema, the agent lacks information about what milestones contain, making the description incomplete.
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?
There are no parameters, and schema coverage is 100%, so the description adds no value here. 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all non-completed milestones' clearly states the verb and resource, but it closely mirrors the tool name and does not differentiate from the sibling tool 'get_milestones_by_status', which could also retrieve non-completed milestones. The purpose is clear but lacks explicit scope.
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 provided on when to use this tool versus alternatives like 'get_milestones_by_status'. The agent receives no information about context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) but not destructive. The description adds no behavioral context beyond what annotations provide, such as potential side effects on other completion paths or authorization needs.
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 sentence of 5 words, highly concise and to the point. It effectively communicates the core action without unnecessary verbosity.
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?
Despite low complexity (2 parameters, no nested objects), the description lacks important context such as the effect on other paths, return value (no output schema), or error conditions. It is insufficient for an agent to fully understand the tool's behavior.
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?
Both parameters are described in the schema with clear names ('id' and 'new_order_index') and descriptions ('Completion path ID', 'New order position'). The description adds no additional semantic value beyond the schema, achieving baseline score given 100% coverage.
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 'Change order_index for a completion path' clearly identifies the verb 'change' and the resource 'order_index' for a 'completion path'. While specific, it does not distinguish itself from sibling tools like 'reorder_all_completion_paths' or 'swap_completion_paths_order'.
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?
The description provides no guidance on when to use this tool, prerequisites, or alternatives. No context signals are given to help an agent decide between this and related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false). The description does not disclose side effects, such as whether changes are persistent, require confirmation, or affect running processes. For a tool that mutates state, more transparency is needed.
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 wasted words. It is appropriately concise for a simple toggle operation.
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 simplicity of the tool (two params, no output schema), the description is mostly complete. However, it lacks information about available feature names (e.g., enums) and the effect of toggling, which would be helpful for correctness.
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 descriptions already cover the meaning of 'feature_name' and 'enabled' with clarity. The description adds no additional information beyond what the schema provides, and schema coverage is 100%, so 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 'Enable/disable tracking feature' clearly states the action (toggle) and resource (tracking feature). It is specific enough to distinguish from sibling tools like 'get_tracking_settings' which reads settings, but does not differentiate from other mutation tools.
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 on when to use this tool versus alternatives. No mention of prerequisites, context, or when not to use it. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds minimal behavioral context beyond the annotations; it does not specify whether updates merge or replace, or what happens if the record_id does not exist.
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 extremely concise at five words. It is front-loaded with action and resource, but could benefit from a bit more detail without becoming verbose.
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?
Given the tool has 3 parameters including a nested object, and no output schema, the description fails to explain return values, error handling, or what constitutes a successful update. It is insufficient for a mutation tool.
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 parameters. The description does not add any new meaning beyond what is in the schema, meeting the baseline of 3.
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 ('Update') and resource ('entry in user settings database'). It is a specific verb+resource combo that distinguishes from sibling tools like add_settings_entry and delete_settings_entry, but does not differentiate from update_user_setting.
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 on when to use this tool versus alternatives such as update_user_setting or add_settings_entry. No context on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds no behavioral detail beyond 'update', missing partial update behavior (NULL means skip) and the fact that no output is returned. No contradiction.
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 'Update subtask metadata' is very concise with no wasted words. However, it could be more informative without losing conciseness.
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?
For a tool with 6 parameters, no output schema, and a partial update pattern, the description is too minimal. It does not explain the NULL convention, idempotency, or return value, leaving gaps for the agent.
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% with clear parameter descriptions. The description does not add extra meaning beyond what the schema provides, so 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?
Description clearly states verb 'update' and resource 'subtask metadata', but does not differentiate from sibling tools like update_task or update_sidequest. The purpose is clear but lacks 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?
No guidance on when to use this tool vs alternatives. Does not mention prerequisites, context, or when not to use. The agent is left to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and non-destructive nature. The description adds no additional behavioral details (e.g., side effects, permissions, response format). It is consistent with annotations but does not augment them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks front-loaded key details. It is not wasteful, but the brevity omits useful context that could aid the agent.
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?
Given the lack of output schema and the large set of sibling tools, the description fails to provide complete context. It does not mention return values, error conditions, or how it relates to other update tools.
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?
Input schema covers all 7 parameters with descriptions (100% coverage). The description adds no per-parameter meaning beyond the schema, meeting the baseline but not compensating for any gaps.
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 states 'Update task metadata' which clearly identifies the operation and resource. However, it does not differentiate from other update tools like update_subtask or update_milestone, missing an opportunity to specify the unique scope.
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 on when to use this tool versus alternatives. No prerequisites, when-not-to-use, or related tool suggestions are provided, leaving the agent without decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive. The description adds no extra behavioral context such as side effects, permission requirements, or the need for the completion path to exist. Minimal transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, it is too short and lacks useful structure or elaboration, making it merely adequate rather than exemplary.
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?
Given the tool has 4 parameters, no output schema, and many sibling tools, the description is too minimal. It does not explain what a milestone is, any constraints, or what the tool returns. More context is needed for effective use.
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%, so the schema already documents all parameters. The description ('Add milestone to completion path') does not add any meaning beyond the parameter names and descriptions. 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 'Add' and the resource 'milestone' with context 'to completion path'. It distinguishes well from sibling tools like add_task or add_subtask which target different entities.
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?
The description provides no guidance on when to use this tool versus alternatives (e.g., update_milestone, delete_milestone, get_milestones_by_path). It does not mention prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read-only operation ('load'), but annotation set readOnlyHint=false, creating a contradiction. No other behavioral traits disclosed.
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?
Single sentence that front-loads the purpose and includes a performance hint. No wasted words.
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?
Lacks return format details, error handling, and explanation of 'preferences'. The annotation contradiction is a significant gap. For a simple one-param tool, more context is needed.
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 covers the single parameter with a description. The description adds no additional meaning beyond what the schema provides, so 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?
Description uses specific verb 'load' and resource 'all active preferences for a directive', clearly distinguishing from sibling tools like add_directive_preference and update_directive_preference which are write operations.
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 explicit guidance on when to use this tool versus alternatives. The parenthetical '(high-frequency)' hints at performance but doesn't explain its significance or compare with other directive-reading tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only, not destructive, and not idempotent. The description adds no additional behavioral context, such as whether the swap is atomic, whether validation occurs, or what side effects might arise.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (single sentence) but lacks necessary supporting details such as usage context or behavioral notes. It is not overly verbose, but the brevity comes at the cost of completeness.
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?
Given the tool's simplicity (two parameters, no output schema), the description should at least mention the expected outcome (e.g., 'Returns success or error') or validation behavior. The current description is too minimal to fully inform an agent.
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 provides 100% coverage with clear descriptions for both parameters ('First completion path ID' and 'Second completion path ID'). The description does not add further meaning beyond what the schema already states, so a 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 clearly states the verb 'Swap' and the resource 'order_index of two completion paths', making the tool's purpose unambiguous. It also differentiates from siblings like 'reorder_completion_path' which handles a single path, and 'reorder_all_completion_paths' which handles all paths.
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 provided on when to use this tool versus alternatives such as 'reorder_completion_path' or 'reorder_all_completion_paths'. The description lacks any context on prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, non-destructive, and idempotent behavior. However, the description adds no further behavioral details, such as whether partial updates are possible, what happens to unspecified functions, or error handling. It fails to elaborate beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which is good for brevity, but it omits important details. It could include more context without significantly increasing length, such as note about atomicity or return value.
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?
Given no output schema and a mutation operation, the description should explain what the tool returns or its side effects. It lacks any mention of success/failure, atomicity, or effects on the file's state. The context is incomplete for an AI agent to use reliably.
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% with descriptions for both parameters. The description does not add any additional meaning or constraints beyond what the schema already provides (e.g., file ID, function update objects). Baseline score 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 'Update multiple functions in a single file', specifying the verb (update), resource (multiple functions), and scope (single file). This distinguishes it from sibling tools like 'update_function' (single function) and 'update_function_file_location' (relocation).
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 provided on when to use this tool versus alternatives. The description does not mention that for updating a single function one should use 'update_function', or any prerequisites or contexts where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only (readOnlyHint=false) and not destructive, which aligns with the description's upsert behavior. The description adds the 'add/update' detail but does not disclose potential side effects, such as whether existing preferences are merged or overwritten.
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. It is concise, though it could benefit from a brief structue highlighting key aspects.
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?
Given the tool has 3 required parameters and no output schema, the description is too minimal. It does not explain what a 'directive preference' is, how the 'active' flag works, or the expected behavior for adding vs updating. Requires additional context to be fully useful.
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%, so the schema already describes each parameter with name, type, and description. The description does not add additional meaning or usage details beyond the schema.
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?
Description clearly states the tool adds or updates a user preference for a directive, which is a specific verb-resource combination. However, it does not differentiate from the sibling 'update_directive_preference' tool, which creates confusion about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'update_directive_preference'. The description does not mention any prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive, which aligns with 'add'. Description adds 'user settings' context but doesn't disclose idempotency, duplicate handling, or permission requirements.
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 with no waste, but may be too minimal for full understanding. Efficient but could benefit from slight elaboration.
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?
For a 2-param tool with nested objects and no output schema, the description leaves many unanswered questions (e.g., valid table names, data format constraints, return value). Incomplete.
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 covers 100% of parameters with basic descriptions. Description adds no additional meaning about expected values or constraints beyond schema.
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?
Description clearly states verb (Add) and resource (entry to user settings database), distinguishing it from update or delete siblings. However, 'entry' is ambiguous and could be more specific, e.g., 'row'.
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 on when to use this tool vs alternatives like add_user_setting or update_settings_entry. No prerequisites or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate the tool is destructive. The description adds 'cross-reference validation' implying additional behavior, but it does not explain what happens to references (e.g., fails if referenced, cascading deletes).
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 sentence with no wasted words, but it is possibly too brief to cover necessary details.
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 description lacks explanation of the note parameters' purpose, the tool's side effects, or any post-deletion behavior. Given the destructive nature and required parameters, more context is needed.
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 100% of parameters with descriptions. The tool description does not add further meaning or explain the rationale for the required note fields.
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 (delete) and the resource (file), and adds the qualifier 'with comprehensive cross-reference validation,' which distinguishes it from other delete tools targeting different entities.
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 provided on when to use this tool versus alternatives, nor are there any prerequisites or context for the required note parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the agent knows it's destructive. The phrase 'with task validation' adds some behavioral context (likely checking for tasks before deletion) but does not clarify what happens if validation fails or if tasks are deleted. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just a few words, no unnecessary content. However, it sacrifices some clarity for brevity.
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 destructive with 5 required parameters, but the description does not explain return behavior, error messages, or the full implications of 'task validation'. No output schema exists, so the description should provide more completeness.
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%, meaning all five parameters have descriptions in the input schema. The tool description does not add any additional meaning beyond what the schema provides, such as how parameters relate to task validation. Baseline 3 applies.
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 'Delete milestone with task validation' clearly states the action (delete) and resource (milestone). It hints at a validation process, distinguishing it from other delete tools, but does not explicitly differentiate from siblings like delete_task.
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 provided on when to use this tool versus alternatives such as delete_task or delete_sidequest. The description implies usage for milestone deletion but lacks any context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds 'with item validation' implying pre-checks but lacks detail on what is validated, side effects (e.g., cascading deletions), or reversibility.
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?
Description is extremely concise (4 words). While concise, it could benefit from slightly more detail without being verbose. Front-loads the key 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?
Given the destructive nature and many sibling deletion tools, the description is too sparse. It does not explain validation, impact on related entities, or error conditions, leaving significant gaps for the agent.
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% with detailed parameter descriptions. The tool description adds no extra meaning beyond what the schema provides, so baseline score of 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 it deletes a task and mentions item validation, distinguishing it from other deletion tools that may not validate items. However, it could be more specific about what validation entails.
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 on when to use delete_task versus sibling delete tools like delete_subtask or delete_item. No mention of prerequisites, consequences, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds 'flow validation', suggesting a check occurs, but does not detail consequences if validation fails, reversibility, or cascading effects.
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 extremely concise at only 5 words, front-loading the core action. However, it may be too brief for a destructive tool, sacrificing information for brevity.
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?
Given 5 required parameters, destructive nature, and no output schema, the description is inadequate. It does not explain 'flow validation', the purpose of note parameters, or expected outcomes, leaving significant gaps.
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 parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline for high coverage.
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 verb 'Delete' and resource 'theme', adding 'with flow validation' to hint at side effects. However, it does not differentiate from sibling delete tools; many others exist with similar patterns.
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 provided on when to use this tool over alternatives like add_theme or update_theme, nor on prerequisites or exclusions. The description lacks any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint) already indicate safe, non-destructive behavior. The description adds context about 'structured JSON conditions' but does not disclose any further behavioral traits (e.g., performance, pagination, or that results are a list). The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence. It is front-loaded with the key concept of flexible filtering. However, it could be slightly expanded to include the resource ('core') without losing efficiency.
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?
Given the tool's complexity (4 parameters, nested object, no output schema) and numerous siblings, the description is insufficient. It does not explain what 'core' refers to, the expected output format, or typical use cases. The annotations compensate partially, but completeness is lacking.
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 baseline is 3. The description's phrase 'structured JSON conditions' adds minimal nuance beyond the schema's 'Field-value pairs (AND logic)'. No additional meaning is provided for table, limit, or orderby.
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 states 'flexible filtering with structured JSON conditions', which clearly indicates it is used for queries with complex conditions on core data. However, it does not explicitly differentiate from sibling tools like get_from_project_where or get_from_settings_where, relying solely on the name to imply the resource.
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?
The description provides no guidance on when to use this tool versus alternatives such as get_from_core or other 'get_where' tools. There is no mention of prerequisites, exclusions, or typical usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotence. The description adds only 'for any parent type' but does not explain what 'incomplete' means, any ordering, pagination, or limits. Minimal added value over annotations.
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 redundant information. It is appropriately short and front-loaded, but could benefit from slightly more detail without becoming verbose.
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?
Given the presence of many specific sibling tools, the description lacks context on how this generic tool differs (e.g., return format, scope of 'incomplete', whether it aggregates across parent types). No output schema is provided, so the description should compensate, but it does not.
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% with clear descriptions for both parameters: for_table (values like tasks, subtasks, sidequests) and for_id (parent ID). The description does not add any additional meaning beyond the schema, so baseline of 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 tool retrieves incomplete items for any parent type, which is a specific verb+resource. However, it does not differentiate from sibling tools like get_incomplete_tasks or get_incomplete_subtasks, as those also get incomplete items but for specific parent types. The purpose is clear but lacks 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?
No guidance on when to use this generic tool versus the many specific sibling tools (e.g., get_incomplete_tasks, get_incomplete_subtasks_by_task). The description does not mention alternatives or exclusions, leaving the agent without decision criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent behavior, reducing the description's burden. The description adds no extra behavioral context (e.g., side effects, performance), which is acceptable for a simple read operation but does not go beyond what is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is ultra-concise (4 words) but lacks additional useful information. While not verbose, it does not earn its place by adding value beyond the name; it is acceptable but minimal.
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 read tool with two parameters, no output schema, and informative annotations, the description is minimally adequate. It does not explain what 'items' are or the relationship to subtask, but the schema partially compensates.
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 covers 100% of parameters with descriptions, so the description does not add additional meaning. The baseline of 3 is appropriate as it neither helps nor hinders understanding of the parameters.
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 tool's action and resource ('Get items for subtask'), matching the name. It implicitly distinguishes from siblings like 'get_items_for_sidequest' by specifying the resource, but it does not explicitly differentiate or provide 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 alternatives. There is no mention of prerequisites, exclusions, or related tools, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds no behavioral context beyond what is provided in annotations, such as error handling or return value details.
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?
Extremely concise single-sentence description with no wasted words. However, it is perhaps too brief and could include more context without sacrificing conciseness.
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?
Given the complexity of sibling tools and absence of output schema, the description is insufficient. It does not explain what a module is, what the return value represents, or potential error conditions.
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% (single parameter 'path'). The description adds no additional meaning beyond the schema's description of 'Directory path to look up', meeting the baseline for full 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 action ('Get module') and the specific identifier ('by directory path'), distinguishing it from sibling tools like 'get_module_by_name'.
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 on when to use this tool versus alternatives; e.g., does not mention that 'get_module_by_path' is for path lookups while 'get_module_by_name' is for name lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, signaling a safe, read-only operation. The description adds minimal value beyond stating 'single entry'; it does not disclose any additional behavioral traits such as behavior when no project exists or response format.
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 concise sentence that front-loads the key information. It is not verbose and earns its place without filler. A slightly longer description could improve clarity without harming conciseness.
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 zero parameters and annotations providing safety guarantees, the description is minimally adequate. However, it does not explain what 'project metadata' includes, leaving the agent to infer from the tool name or sibling tools. An output schema would help, but it is absent.
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 input schema has zero parameters, so the description does not need to add semantics. Schema coverage is 100% trivially, meeting the baseline of 3; the description adds no new parameter information but is not required to.
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 'Get project metadata (single entry)' clearly specifies the verb and resource, distinguishing it from sibling tools like get_project_fields or get_project_schema. It indicates that this tool retrieves the entire project metadata as a single record, which is unique among siblings.
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 provided on when to use this tool versus alternative sibling tools that retrieve specific subsets of project data (e.g., get_project_fields, get_project_json_parameters). There is no mention of prerequisites or context that would help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds minimal extra behavioral context beyond 'complex' and 'rare use'. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence with parenthetical) and front-loads the core action. While concise, it could be slightly more informative without being verbose. No extraneous content.
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 description lacks information about return values or error behavior. Given there is no output schema, the agent is left to infer what the tool returns. For a simple query tool, this is a notable 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%, with clear descriptions for both parameters ('Table name in user_preferences.db' and 'SQL WHERE clause for filtering'). The description adds no additional meaning beyond the schema, resulting in a baseline score.
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 it executes a complex SQL WHERE clause, which is a specific action on a resource. It implies direct SQL execution, distinguishing it from more structured query tools, though not explicitly naming siblings.
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?
The phrase '(advanced, rare use)' hints at non-routine usage but provides no explicit guidance on when to use this tool versus alternatives like get_from_settings or query_core. There is no mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (no readOnly, destructive hints), and the description does not disclose behavioral traits such as whether the operation is reversible, if it modifies all paths globally, or what happens to other order_index values. The description adds minimal context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and what is being fixed. No unnecessary words. It is efficiently structured.
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?
Given no output schema and minimal annotations, the description should explain the outcome (e.g., resulting order_index values, side effects) and confirm it acts on all completion paths. The current description is too brief for a complete understanding.
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?
There are no parameters, so schema coverage is 100%. The description does not need to add parameter info. The score is baseline 4 for zero-parameter tools.
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 'Fix gaps and duplicates in order_index' clearly indicates the tool's purpose: it reorders completion paths to correct ordering issues. The name and title reinforce this. However, it lacks an explicit verb like 'reorder', and could be more specific about the scope (all paths).
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 on when to use this tool versus siblings like 'reorder_completion_path' or 'swap_completion_paths_order'. The description does not mention prerequisites, alternatives, or when not to use it. Usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds minimal behavioral context beyond mentioning optional filters. It does not describe pagination, result ordering, or search behavior.
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 concise sentence that captures the essence. It could be slightly more informative but is not overly verbose.
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 multiple optional filters and no output schema, yet the description does not explain how filters combine (AND/OR) or what the return format looks like. Missing details for a search tool with moderate 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?
Input schema has 100% coverage with descriptions for all parameters. The description does not add meaning beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches tracking note content with optional filters, using a specific verb and resource. However, it does not differentiate from the sibling tool search_notes, which likely has similar functionality.
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 provided on when to use this tool versus alternatives like get_tracking_notes or search_notes. The description lacks any contextual hints for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context (e.g., side effects, authorization needs). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (5 words) but effectively communicates the core purpose. While concise, it could benefit from slightly more structure without being verbose.
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 description is minimally adequate: it clarifies that only the role is updated, which is important given the sibling update tools. However, it lacks information about return values, effects on related data, or prerequisites.
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 description adds no extra meaning to the parameters beyond their schema descriptions. The baseline of 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 explicitly states 'Update relationship role only', clearly indicating the verb (update) and resource (role of a type-function relationship). It is distinguishable from sibling update tools like update_type or update_function, though it doesn't name specific 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 on when to use this tool versus other update tools or alternatives. The description provides no context about prerequisites, typical scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) already indicate a safe, non-destructive write operation. The description adds no further behavioral details, such as error behavior if record_id is missing or the effect on other fields not specified in 'data'.
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 is concise and front-loaded. However, it lacks structure such as usage hints or examples. Not overly verbose, but could benefit from more information without sacrificing conciseness.
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?
Description is minimal for a tool with 3 required parameters, including a nested object ('data'), no output schema, and many sibling tools. Missing information about expected format of 'data', whether partial updates are allowed, and relationship to other user_custom operations.
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 descriptions already cover all three parameters (table, record_id, data) with 100% coverage. The description's phrase 'Update entry' aligns with the data parameter but adds no additional meaning beyond 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?
Description clearly states 'Update entry in user_directives.db table', specifying the verb 'update' and resource 'entry in user_directives.db table'. Differentiates from siblings like 'add_user_custom_entry' and 'delete_user_custom_entry' which perform different actions.
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 on when to use this tool versus alternatives such as 'add_user_custom_entry' or 'delete_user_custom_entry'. No mention of prerequisites, constraints, or when not to use it. Single sentence provides no contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it adds an entry and returns the inserted record, which aligns with readOnlyHint=false. However, no mention of side effects, error scenarios (e.g., duplicate key, constraints), or behavior if table is missing. Annotations provide no additional context, so description carries the burden but falls short of full transparency.
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?
Two short statements: action and return. No redundant words. Front-loaded with the verb. Could be slightly more structured but highly concise.
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?
Covers basic purpose and return value, but lacks broader context. Given the large set of sibling tools, the description does not explain what 'user_directives.db' is or how this tool relates to others (e.g., get_from_user_custom, update_user_custom_entry). Adequate for isolated use but incomplete for an agent navigating many similar tools.
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 baseline is 3. The description does not add new information about parameters; it merely echoes the schema. No extra semantics or usage tips are provided.
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?
Description clearly states action (add entry), target (user_directives.db table), and return value (inserted record with ID). However, it does not differentiate from many other 'add_*' sibling tools, leaving ambiguity about the specific type of entry.
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 usage guidance provided. Does not specify when to use this tool over alternatives like update_user_custom_entry or add_user_directive_note. Lacks any context about prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not destructive, which aligns with creating a new entry. The description adds the 'one per database' constraint but does not specify behavior on duplicate, error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (4 words) with no unnecessary content. It delivers the core purpose efficiently, though it could be slightly more informative without losing conciseness.
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 description lacks details about return values, error states, or success indicators. Given no output schema, this information would be helpful. The constraint 'one per database' is mentioned but not fully explained.
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?
Input schema descriptions cover all parameters (100%), so the description does not need to add much. It does not provide any additional meaning beyond the schema.
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 tool initializes a project entry with the constraint 'one per database'. However, it does not distinguish from the sibling 'add_project_entry', which likely has a different scope.
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 provided on when to use this tool versus alternatives (e.g., 'add_project_entry', 'update_project'). The description lacks context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-write and non-destructive behavior, but the description adds minimal behavioral context beyond the naming convention. It does not disclose what happens if the branch already exists, whether it creates a git branch or something else, or any side effects. This leaves significant ambiguity for a creation tool.
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 conveys the essential purpose and naming convention. It is front-loaded and concise, with no unnecessary words or repetition.
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?
Given the tool has two required parameters and no output schema, the description is too sparse. It fails to explain what exactly is created (e.g., a git branch), what the return value is, or any constraints. For a creation tool with no output schema, more detail is needed for full understanding.
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% with descriptions for both parameters. The description adds no extra meaning beyond the schema; it only implies that the 'number' part of the convention is handled internally. Baseline of 3 is appropriate since schema already documents parameter purposes adequately.
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 it creates a work branch following a specific naming convention (aimfp-{user}-{number}), which is a specific verb+resource. However, it does not differentiate from sibling tools that create other entities like create_project or create_state_database, but since there is no other branch creation tool, this is acceptable.
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 when a new work branch is needed, but provides no explicit guidance on when not to use it, prerequisites (e.g., user existence), or alternatives. The naming convention hints at usage context but lacks exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's mention of 'validation and interaction cascade' adds some behavioral context. However, it does not detail what the cascade entails (e.g., which interactions are deleted) or any irreversible effects, limiting transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but very brief. It front-loads the action but lacks structure or detail. It earns its place but could be more informative without added length.
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?
Given the complexity (5 required params, no output schema, annotations provided), the description is insufficient. It does not explain the 'interaction cascade', return value, or preconditions, leaving the agent with gaps.
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 each parameter is well-described in the input schema. The description adds no additional meaning beyond what the schema provides, so 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 action 'Delete' and the target 'function', and adds 'with validation and interaction cascade' to specify additional behavior. This distinguishes it from other delete tools among siblings (e.g., delete_file, delete_note).
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?
The description does not provide guidance on when to use this tool vs alternatives. It lacks explicit context, exclusions, or references to sibling tools. The agent is left to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds the 'discouraged' label, which gives behavioral context beyond annotations. However, it doesn't disclose permanence, cascading effects, or authorization needs, so it only partially enhances transparency.
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?
At three words, the description is extremely concise and front-loaded with the verb. Every word earns its place, though a slightly longer description could add value without hurting conciseness.
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 delete tool with one parameter and clear annotations, the description is adequate. However, it omits details about return value, side effects, or when deletion is irreversible, leaving some gaps in completeness.
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% with a clear description for the 'id' parameter. The description adds no extra semantics beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete note (discouraged)' clearly identifies the verb and resource. It distinguishes from sibling tools like add_note and update_note. However, it lacks explicit scope or side effects, preventing a perfect score.
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?
The description includes '(discouraged)' as minimal guidance, implying the tool should be avoided. But it fails to specify when or when not to use it, nor does it suggest alternatives like update_note. This leaves agents without clear decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's addition of 'with item validation (same logic as delete_task)' provides some behavioral context but does not elaborate on consequences, reversibility, or specific behaviors beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with ~10 words, no fluff, and directly states the action. Every word earns its place.
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?
No output schema exists, yet the description does not explain return values or success/failure indicators. For a destructive tool, this is a significant gap. The description also lacks comprehensive context for usage among many siblings.
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% with individual parameter descriptions. The description adds no additional meaning beyond what the schema already provides, meeting the baseline expectation.
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 'Delete subtask', which is a specific verb and resource. It adds 'with item validation' for context but does not differentiate from the sibling delete_task beyond the resource name.
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 on when to use this tool versus alternatives like delete_task. The description does not provide any context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral detail that the tool updates the 'work_branches' table on success, which goes beyond annotations. Annotations already mark the tool as destructive (destructiveHint=true). The description does not elaborate on failure behavior, side effects on the repository, or permissions required, but it provides some additional context.
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 extremely concise—two short sentences that efficiently convey the primary action and a key side effect. No unnecessary words or repetition; every sentence earns its place.
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?
Despite being concise, the description lacks important context. It does not specify the target branch (presumably the current branch), how conflicts are handled, whether the merge is committed automatically, or what the 'result' contains. For a destructive merge tool with no output schema, more detail is needed for safe and correct usage.
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 has 100% coverage: source_branch is described as 'Branch to merge from'. The description does not add any further meaning beyond what the schema provides. With full schema coverage, the baseline of 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 tool executes a git merge and returns a result. It specifies the action and the resource (git merge), making the purpose clear. However, it does not differentiate from siblings like 'detect_conflicts_before_merge' which is a related but distinct action.
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 usage guidance is provided. The description does not indicate when to use this tool versus alternatives (e.g., detect_conflicts_before_merge for pre-checking, or sync_git_state for syncing state). There is no mention of prerequisites, such as being on the target branch or having no existing conflicts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint and idempotentHint. The description adds that results are filtered by type, but does not disclose return format, pagination, or potential errors. Given the safety profile from annotations, the description is adequate but not revealing beyond the schema.
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 sentence with 10 words, focusing on the core function. It is efficient but could be clearer about the type mapping. It earns its place without redundancy.
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 read-only filtered list tool with 2 parameters and no output schema, the description is mostly complete but lacks clarification on the type mapping (orchestration vs reference) and does not differentiate from siblings like get_directives_by_category. Given the number of siblings, more context would help.
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%, with clear descriptions for both parameters. The description adds a high-level categorization ('orchestration vs reference') that is not defined and may not match the enum values. For include_md_content, the description adds nothing. Minimal added value beyond schema.
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 (get) and resource (directives) with a filter by type. It distinguishes from sibling tools like get_all_directives (no filter) and get_directive_by_name. However, the mention of 'orchestration vs reference' is ambiguous and does not align with the explicit enum values in the schema, causing some confusion.
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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclude cases (e.g., when to use get_all_directives instead). Among many sibling tools, this omission makes it harder for the agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds 'return full directive objects,' which is consistent but adds minimal new behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it could benefit from slightly more structure (e.g., noting that it requires keywords).
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 3 parameters with 100% schema coverage and no output schema, the description is adequate but could specify output details or usage constraints. It is missing some context that would help an agent fully understand the tool's behavior.
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%, so the schema fully describes parameters. The description does not add extra meaning beyond 'search by intent keywords,' which is already implied by the name and schema.
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 states 'Search directives by intent keywords and return full directive objects,' which specifies the verb (search), resource (directives), and return type. It is clear but does not differentiate from sibling tools like 'find_directives_by_intent_keyword' that likely do similar things.
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 on when to use this tool versus alternatives. The description lacks any when/not-to-use context or mention of sibling tools that might be more appropriate for certain scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description aligns with these but adds no new behavioral details. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one short sentence, concise and front-loaded. Could be slightly more informative without losing conciseness.
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 low complexity (1 param, no output schema), the description is minimally adequate. However, it lacks usage guidance and differentiation, leaving some gaps for context.
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%, so the description adds no extra meaning beyond what the schema already provides for the single parameter. Baseline score of 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?
Description clearly states verb 'get' and resource 'file IDs associated with flows', making purpose clear. However, it does not distinguish from sibling tools like 'get_files_by_flow' or 'get_files_by_flow_context', which operate on similar data.
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 on when to use this tool versus alternatives. Does not mention context, exclusions, or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, which indicate safe, idempotent behavior. The description adds no behavioral trait beyond 'fairly frequent', which is a usage frequency note. This does not contradict annotations but adds minimal value.
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 sentence with a parenthetical, making it very concise. It is front-loaded with the core function. The parenthetical is slightly informal but not detrimental.
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 lookup tool with one parameter and safety annotations, the description is minimally adequate. However, it does not describe what the return value is (a flow object), which would be helpful given no output schema. It is sufficient but could be more informative.
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 has one parameter 'flow_name' with description 'Flow name to look up', achieving 100% schema coverage. The description adds no additional information about the parameter, so it meets the baseline but does not enhance understanding.
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 'Get flow by name (fairly frequent)' clearly states the action (get) and resource (flow by name). However, it does not differentiate from sibling tools like get_all_flows or get_flows_for_file, which retrieve flow data in different ways.
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?
The description provides no guidance on when to use this tool versus alternatives. The parenthetical 'fairly frequent' implies common usage but offers no context, exclusions, or conditions for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and idempotent. The description adds the behavioral constraint that empty arrays are not allowed, which is useful. However, it does not explain the error behavior or return format, leaving gaps for a complete understanding.
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 very concise, using a single sentence to convey the core purpose and a key constraint. It is front-loaded and wastes no words. However, it could be slightly more informative without losing brevity.
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 simplicity of the tool (2 required params, no output schema), the description is minimally adequate. It covers the basic action and the empty array constraint, but lacks details on return values, error conditions, or usage examples. It is functional but not thorough.
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%, with both parameters well-described in the schema. The description does not add new semantic information beyond what is in the schema; it only repeats the constraint. According to the rubric, baseline is 3 when coverage is high, so this score 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 tool gets records by IDs, which is a specific verb+resource. It also highlights the constraint that empty arrays are not allowed. However, it does not differentiate from sibling tools like get_from_project_where or query_project, which could lead to confusion about when to use this exact tool.
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 provided on when to use this tool versus alternatives. The description offers no context about prerequisites, limitations, or when it is preferable to use get_from_project over similar retrieval tools such as get_from_project_where or query_project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds minimal behavioral context with 'comprehensive' and 'orchestrator', which hint at scope but lack detail. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is concise but could benefit from a bit more detail without becoming verbose.
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?
With no output schema and a vague 'comprehensive' claim, the description is incomplete. It does not clarify what the snapshot includes (e.g., branch, changes, stashes), leaving the agent uncertain about the tool's output.
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, and the schema documentation coverage is 100% (empty). Per guidelines, baseline 4 is appropriate. The description does not need to explain parameters further.
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?
Description clearly states verb 'Get' and resource 'comprehensive Git state snapshot', distinguishing it from sibling tools that retrieve individual Git details like get_current_branch or get_current_commit_hash. However, the term '(orchestrator)' is ambiguous and could be more precise.
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 provided on when to use this tool versus alternatives such as sync_git_state or individual getters. The description does not mention any prerequisites or contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats the tool's name. Annotations already provide readOnlyHint=true and idempotentHint=true, so the description adds no behavioral context beyond the structured fields.
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 extremely concise and front-loaded, consisting of a single phrase that conveys the core purpose without any waste.
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 no-parameter read tool, the description is adequate but minimal. It does not explain what 'completion paths' are or what 'non-completed' means precisely, which could leave some ambiguity.
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 input schema has zero parameters, so the description does not need to add parameter meaning. Baseline of 4 is appropriate for no parameters.
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 'Get all non-completed paths' clearly states the tool returns paths that are not completed. However, it does not distinguish from siblings like get_all_completion_paths or get_completion_paths_by_status, which could cause confusion.
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 provided on when to use this tool versus alternatives. There are many sibling tools with similar purposes (e.g., get_all_completion_paths, get_completion_paths_by_status), and the description offers no context for choosing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe query. The description adds little beyond the filter 'non-completed' and does not elaborate on what constitutes completion or other behavioral details.
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?
Extremely concise with a single sentence that clearly conveys the purpose. No unnecessary information.
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?
Adequate for a simple getter with no parameters. However, without an output schema, the description could hint at what fields are returned. The context of sibling tools is strong, but the description does not leverage it.
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?
No parameters exist, so there is nothing to explain. Schema coverage is 100%, meeting the baseline for zero parameters.
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?
Clearly states it retrieves non-completed subtasks. However, it does not specify the scope (e.g., all tasks globally vs. a specific task), which could be ambiguous given sibling tools like get_incomplete_subtasks_by_task.
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 on when to use this tool versus alternatives such as get_incomplete_subtasks_by_task or get_subtasks_comprehensive. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds that files are retrieved via flows, but does not disclose return format or what 'files related' means (e.g., metadata or content). Moderate additional context.
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?
Single sentence with clear verb and resource, no unnecessary words. Front-loaded and efficient.
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?
Lacks details on return structure (what constitutes a file), how flows orchestrate the retrieval, and when to prefer this over siblings. For a tool with no output schema, the description should provide more completeness.
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 'sidequest_id' is fully described in the schema (100% coverage). Description restates 'related to sidequest' but adds no new semantics beyond the schema.
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?
Description clearly states verb 'Get' and resource 'all files related to sidequest', and specifies the mechanism 'via flows (orchestrator)', distinguishing it from siblings like get_files_by_flow or get_sidequest_flows. However, 'orchestrator' is jargon and could be clearer.
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 on when to use this tool versus alternatives such as get_files_by_flow or get_sidequest_flows. The description does not mention use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds no behavioral details beyond the title. It does not disclose that this is a read-only, idempotent operation, nor does it provide additional context about rate limits or cost.
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 extremely concise with two phrases, front-loading the core purpose. Every word earns its place given the tool's simplicity.
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?
With no output schema, the description should at least hint at the return structure. It does not explain what a 'theme' is or what fields are returned. For a simple getter, it is insufficiently 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 coverage is 100% with a clear description of the 'theme_name' parameter. The tool description adds no extra information beyond what the schema already provides. Baseline 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 clearly states the tool's function: retrieving a theme by name. It distinguishes it from sibling tools like 'get_all_themes' or 'get_themes_for_flow' by specifying the lookup key.
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 usage guidelines are provided. The description does not tell when to use this tool versus alternatives like 'get_all_themes', nor does it mention prerequisites or performance considerations beyond the vague 'fairly frequent'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, indicating safe, non-mutating behavior. The description adds the concept of 'optional filters' but does not disclose any additional behavioral traits such as result limits, sorting, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It efficiently conveys the core 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?
Despite having 5 optional parameters, the description lacks details about the return format, pagination, or how this tool differs from similar ones. Given the complexity of the sibling set, more context would be beneficial for correct selection.
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?
With 100% schema description coverage, each parameter already has a 'Filter by ...' description in the schema. The tool description does not add extra semantic information beyond what's in the schema, so the value added is neutral.
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 'Get tracking notes with optional filters' clearly specifies the verb ('Get') and resource ('tracking notes') and mentions filtering capability. However, it does not differentiate from sibling tools like 'get_notes_comprehensive' or 'search_tracking_notes', which may cause confusion about which tool to use.
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?
The description provides no guidance on when to use this tool versus alternatives. Given siblings like 'search_tracking_notes' and 'get_notes_comprehensive', explicit context on when to choose this tool over others is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's safety profile is covered. The description adds no behavioral traits beyond what the schema provides (e.g., case-insensitive LIKE match is in schema). Adequate but no extra context.
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, concise sentence that is front-loaded with the key action and resource. No wasted words, but it could be slightly expanded with more context without losing conciseness.
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 6 parameters and no output schema, the description is minimal. It explains what the tool does but does not describe return values or integrate filter details. Acceptable but could be more comprehensive for a search tool.
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 baseline is 3. The description mentions 'optional additional filters' but does not elaborate on each parameter. The schema already provides descriptions, so the description adds no extra meaning.
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 verb 'Search', the resource 'note content in user_directives.db', and mentions optional filters. It distinguishes from siblings like 'search_notes' (different database) and 'search_user_directives' (entire directives, not notes), but does not explicitly differentiate.
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?
The description provides no guidance on when to use this tool versus alternatives, such as other search tools like 'search_notes' or 'search_user_directives'. No when-not-to or context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as non-read-only, non-destructive, and idempotent. The description adds no further behavioral context, such as what happens to unspecified fields (though the schema indicates NULL means no update) or any side effects. The value added beyond annotations is minimal.
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, short sentence with no wasted words. While concise, it could be slightly more informative without adding bulk. Structure is minimal but acceptable.
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 tool with 6 parameters and no output schema, the description is minimal. It lacks context about return values, prerequisites, or when updates take effect. Annotations help, but the description could be more complete given the tool's 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?
Schema description coverage is 100%, and each parameter's description clarifies that NULL means 'don't update'. The tool description does not add any additional meaning, but the schema itself is self-explanatory. 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 'Update project metadata' clearly specifies the action (update) and the resource (project metadata). It distinguishes this tool from siblings that update other entities like files, flows, or themes, and from create_project or get_project.
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?
The description provides no guidance on when to use this tool versus alternatives such as create_project, get_project, or other update_* tools. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. Description adds that it triggers note creation, which is a behavioral detail beyond annotations. However, no mention of permissions or side effects for specific actions.
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?
Two concise sentences. Information is front-loaded, but structure could be improved with bullet points or explicit sections. No wasted words.
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?
Description provides high-level behavior but omits return values (no output schema). With many sibling tools, more context on when use is preferred would improve completeness. Adequate but not rich.
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%, so parameters are already documented. Description adds context about actions mapping to status updates but does not elaborate on action-specific effects or data field contents. Marginal added value beyond schema.
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?
Description states it handles state changes for tasks, milestones, and paths, mapping actions to status updates and note creation. Purpose is clear but does not explicitly differentiate from sibling update tools like update_task or update_milestone.
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 on when to use this tool vs alternatives like update_task, update_milestone, or specific action tools. It implies usage for orchestrated state transitions but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, so the description's generic 'Update' adds no new behavioral insights. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that directly states the purpose. It is front-loaded, but could arguably include more useful context without being verbose.
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 8 parameters and absence of output schema, the description is minimal. The schema covers parameters well, but the description lacks context on what 'metadata' encompasses, which is partially mitigated by schema completeness.
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?
With 100% schema coverage, the baseline is 3. The description does not add any meaning beyond the schema's parameter descriptions, which are already detailed.
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 'Update sidequest metadata' clearly specifies a verb and resource, but it does not distinguish this tool from many sibling 'update_' tools. It lacks specificity on what metadata fields are included.
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 on when to use this tool versus alternatives like update_task or update_subtask. No prerequisites or context provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and non-destructive nature. Description adds little beyond stating it's an update. No disclosure of side effects, error behavior, or permissions. Since annotations carry the burden, a 3 is appropriate.
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 redundant information. Could include a bit more detail without becoming verbose, but it is appropriately concise.
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?
No output schema and no description of return values or error states. For a simple update tool with good annotations, it covers basics but lacks completeness on behavioral outcomes.
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?
All parameters have descriptions in the input schema (100% coverage). The tool description does not add any additional meaning or context for the parameters, so baseline 3 is correct.
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?
Description states verb 'Update' and resource 'existing project-wide user setting in user_settings table', making the tool's purpose clear. It distinguishes from siblings like get_user_setting (read) and add_user_setting (create), but could be more specific about what constitutes a user setting.
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 on when to use versus alternatives, prerequisites (e.g., setting must exist), or when not to use. Does not mention that add_user_setting should be used for new settings or that get_user_setting is for reading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds 'file validation' hinting at additional side effects, but does not elaborate on what validation occurs or its implications.
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?
Extremely concise at 5 words, no fluff. However, could benefit from more detail without becoming verbose.
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?
For a destructive mutation with 5 required parameters and no output schema, the description lacks details on post-deletion effects, file validation specifics, and typical use case context.
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?
All 5 parameters are described in the input schema with clear descriptions. The description adds no further meaning beyond what the schema already provides.
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 'Delete flow with file validation' clearly states the action (delete) and resource (flow) with a specific qualifier (file validation), distinguishing it from other delete tools in 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use delete_flow versus alternatives like delete_file or update_flow. No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds 'with relationship validation', hinting at dependency checking before deletion, but does not detail the behavior on validation failure or other aspects like cascading or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 4 words, front-loaded with the key action, but could benefit from additional context without being too verbose.
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 description lacks explanation of the relationship validation process, what happens when validation fails, and the role of the required note parameters. Given 5 required parameters and no output schema, more context is needed for a deletion tool.
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 baseline is 3. The description adds no extra meaning about parameters; the note parameters are not explained in relation to the deletion process.
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 'Delete' and the resource 'type', and adds the behavioral trait 'with relationship validation', which distinguishes it from other delete tools and provides specific context.
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 usage guidelines are provided. The description does not indicate when to use this tool over alternatives such as update_type or other delete tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that it compares HEAD to a specific hash, but does not disclose what happens on mismatch or the output format.
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, no redundant words, and the core action is front-loaded. Excellent conciseness.
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?
Lacks any description of return value or how to interpret results. Does not explain what project.last_known_git_hash represents. Given no output schema, this gap hinders the agent.
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?
No parameters, and schema coverage is 100%, so the description does not need to explain inputs. Baseline 4 for zero-parameter tools.
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 tool compares current Git HEAD with a stored hash, specifying the verb and resource. However, it does not differentiate from siblings like get_git_status or sync_git_state, missing a chance to clarify its unique role.
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 on when to use this tool versus alternatives (e.g., get_git_status, sync_git_state). The agent must infer context from the name and siblings alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, so safety and idempotency are clear. The description adds no further behavioral traits (e.g., return on missing category), but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at one sentence. No fluff, though the parenthetical '(fairly frequent)' is non-essential but not harmful.
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?
For a simple lookup tool with no output schema, the description should indicate what is returned (e.g., category object, null, or error). It fails to provide this context, making it incomplete.
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% for the single parameter. The description adds no extra meaning beyond the schema's 'Category name'.
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 'Get category by name', identifying the specific verb and resource. It implicitly distinguishes from sibling tools like 'get_categories' which retrieves all categories.
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 on when to use this tool versus alternatives. The parenthetical '(fairly frequent)' provides no usage context. Missing explicit when/when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety profile is clear. The description adds minimal behavioral context beyond that, not addressing potential behaviors like pagination, rate limits, or response size.
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, highly concise and front-loaded. Every sentence adds value: first states purpose, second quantifies benefit. No wasted words.
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 parameter count and lack of output schema, the description adequately explains the tool's role as a consolidated query. However, it doesn't specify the return format or structure, which would help the agent anticipate the response.
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%, so the schema already documents each parameter. The description adds little extra meaning beyond 'scoped' and 'flexible query', which aligns with the schema. 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 it's a single entry point for scoped project status queries, replacing multiple helper calls. It distinguishes from siblings by positioning itself as a consolidated query tool, though it doesn't explicitly name which siblings it replaces.
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 for broad overviews instead of multiple specific calls, but lacks explicit when-not conditions or alternatives. Without guidance on when to use specific getters instead, the agent has to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds the constraint that empty array is not allowed, which is useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with bold emphasis for key constraint. Very concise and front-loaded.
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?
No output schema and no description of return value. For a tool that fetches records, agent needs to know what is returned (e.g., rows, structure). Minimal context.
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?
Input schema has 100% description coverage, so schema already explains parameters. Description adds no new meaning beyond repeating database name.
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?
Clearly states 'Get records by ID(s) from user_directives.db' with a specific constraint. Differentiates from sibling 'get_from_user_custom_where' which implies filtering by conditions.
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 on when to use this tool versus alternatives like 'get_from_user_custom_where' or other getters. Only mentions when not to use (empty array not allowed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to reiterate safety. The description adds no behavioral details beyond the annotations (e.g., no mention of return format or side effects), but it does not contradict them.
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, complete sentence with no unnecessary words. It is front-loaded and efficient.
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 simple parameter and good annotations, the description is minimally complete. However, it does not detail the output format (what constitutes a 'helper'), which could be helpful for an AI agent, especially since no output schema is provided.
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 fully describes the single parameter 'target_database' with its constraints, achieving 100% coverage. The description adds no extra semantics or examples, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('get all helpers') and the resource ('for a specific database'). It is specific enough to distinguish from sibling tools that retrieve helpers by name or directive, though it does not explicitly differentiate them.
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?
The description provides no guidance on when to use this tool versus alternatives like 'get_helper_by_name' or 'get_helpers_for_directive'. It lacks context on prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and idempotentHint true, so the tool is safe and idempotent. The description adds no behavioral context beyond what annotations provide, such as pagination or ordering.
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 concise sentence that front-loads the core purpose. No wasted words.
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 returns items, but the description does not specify the structure or content of the output. With no output schema, more detail would be beneficial for completeness.
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% with descriptions for both parameters. The description repeats 'optionally filtered by status' but adds no additional meaning beyond the schema.
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 ('get items') and resource ('for task'), with an optional filter. While it is distinct from siblings like get_items_for_sidequest, it does not explicitly differentiate itself, which would earn 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_items_for_sidequest or get_incomplete_items. The description provides no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, so the description's warning 'complex' and 'rare use' adds minor behavioral context about potential performance. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with key qualifiers ('complex', 'advanced', 'rare use') front-loaded. No redundancy, every word adds value.
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?
Tool is simple with good annotations and no output schema, but description omits that it targets core tables (implied by name but not explicit). Minimal but adequate for a rare-use tool.
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 covers both parameters with descriptions (100% coverage). The description adds no new parameter meaning beyond reinforcing that 'query' is a WHERE clause, achieving baseline expectations.
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 tool executes a SQL WHERE clause, with 'complex' and 'rare use' indicating advanced capability. It distinguishes from simpler get-functions among siblings, though it doesn't explicitly contrast with 'get_from_core_where'.
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?
The phrase 'advanced, rare use' implies the tool should be used sparingly, but no explicit guidance on when to prefer it over sibling tools like 'get_from_core_where' or specific field retrieval functions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint: true and destructiveHint: false, but the description does not reinforce these traits or explain side effects. It adds minimal behavioral context beyond the schema's 'NULL = don't update' hint.
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, direct sentence with no superfluous words. It is appropriately brief for a simple update operation.
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 description covers the basic purpose but omits details like partial update behavior (only non-null fields are updated) and return value expectations (no output schema). For a tool with 4 parameters and no output schema, more context would improve completeness.
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%, so all parameters are already documented. The description adds no additional meaning or usage tips beyond what is in the schema, resulting in a baseline score.
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 ('update') and resource ('flow metadata'), indicating the tool modifies metadata fields of a flow. It is sufficiently specific among siblings like 'update_theme' or 'update_type', though it doesn't enumerate the exact fields.
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 provided on when to use this tool versus other update tools (e.g., 'update_theme', 'update_file'). There is no mention of prerequisites, alternatives, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false. The description adds 'Only non-None fields are updated,' which goes beyond the schema but does not disclose potential side effects or return value. With annotations covering safety, this description adds marginal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no redundancy, and front-loaded with purpose. 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?
For a mutation tool with 6 parameters and no output schema, the description is adequate but lacks details on success/failure outcomes or return format. The idempotent behavior is hinted but not fully explained.
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?
Input schema covers 100% of parameters with descriptions. The description adds no additional meaning beyond the schema, so baseline score of 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 'Update module metadata' using a specific verb and resource. However, it does not distinguish from sibling update tools like update_file or update_function, which share similar structures.
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 on when to use this tool versus alternatives like add_module or get_module_by_name. The only behavioral note ('Only non-None fields are updated') is about operation mechanics, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) indicate mutation but non-destructive. Description adds that it creates a junction entry and follows the same pattern as add_file_to_flow. However, does not describe side effects, error conditions, or behavior if file already assigned to module.
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 short sentences with no unnecessary words. Front-loaded with the core action. Every sentence is meaningful.
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 junction creation tool with full schema coverage and no output schema, the description is adequate. It explains the purpose and pattern. Could hint at return value or idempotency, but not critical.
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% with clear descriptions for both parameters ('File ID to assign', 'Module ID to assign to'). Description does not add further meaning beyond the schema.
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?
Description clearly states the tool assigns a file to a module and creates a module_files junction entry. It mentions the same pattern as add_file_to_flow, which helps distinguish it from siblings like add_files_to_module or remove_file_from_module.
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 on when to use this tool versus alternatives like add_files_to_module (bulk) or remove_file_from_module. Also no mention of prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint=true). The description adds 'with milestone validation', indicating a check before deletion, which provides extra context beyond annotations. However, it does not detail validation behavior or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that delivers the core purpose without any filler. Every word is necessary, and it is front-loaded with the key action.
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?
Despite having 5 required parameters, a destructive annotation, and no output schema, the description is extremely brief. It omits crucial context such as prerequisites, return behavior, error handling, or what happens upon validation failure. For a safe and effective invocation, the description is insufficient.
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 has 100% description coverage for its 5 parameters, so the description carries less burden. The phrase 'with milestone validation' hints at the purpose but does not add specific meaning to any parameter beyond what the schema already provides.
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 'Delete' and the resource 'completion path', and adds specific context 'with milestone validation', which distinguishes it from other delete operations like delete_milestone or delete_task. It fully conveys the tool's purpose.
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?
The description provides no guidance on when to use this tool versus alternatives such as delete_milestone or other deletion tools. It lacks explicit instructions on prerequisites, conditions, or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so basic safety is clear. The description adds valuable context beyond annotations: 'Returns raw flow data - AI evaluates conditions' indicates that the output is intermediate raw data requiring further AI processing, which informs agent behavior.
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 front-loading the purpose. It avoids unnecessary detail but could be slightly more structured (e.g., listing return type). Still, it is efficient and clear.
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 simplicity (one param, no output schema), the description provides the core idea but lacks specifics on the return value structure (what fields are in 'raw flow data'). Additional detail on output format would improve completeness for agent processing.
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 has 100% coverage for the single parameter 'from_directive' with a clear description. The tool description does not add further meaning or nuance, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all flows originating from a directive' and adds the clarifying parenthetical '(what comes next?)' which gives semantic context. However, it does not differentiate from similar siblings like 'get_directive_flows' or 'get_flows_to_directive', which could cause confusion.
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 explicit guidance on when to use this tool versus alternatives. The description does not mention when-not to use it or provide comparisons to similar flow retrieval tools, leaving the agent to infer usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety and idempotency. The description adds 'high-frequency', hinting at usage pattern but no specific behaviors (e.g., rate limits, side effects). With annotations doing heavy lifting, the description provides minimal extra 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?
The description is a single sentence of four words, containing no fluff or redundancy. It is front-loaded with the core action and resource, achieving maximum conciseness with zero waste.
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 lookup tool with comprehensive annotations (read-only, idempotent) and no output schema, the brief description is largely adequate. However, it does not specify what 'details' are returned (e.g., structure, fields), which slightly reduces completeness.
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% with a clear parameter description 'Helper name to look up'. The tool description adds no additional meaning beyond the schema; it simply restates the purpose. Baseline 3 applies as the schema already documents the parameter adequately.
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 'Get specific helper function details (high-frequency)' uses a specific verb and resource, clearly indicating a lookup by name. However, it does not explicitly differentiate from sibling tools like get_helpers_are_sub or get_all_helpers, though the 'by name' specificity is implied.
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 provided on when to use this tool versus alternatives such as get_helper_by_name vs get_all_helpers. The description lacks context for usage exclusions, prerequisites, or comparisons, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare safe, idempotent read operation. The description adds that the tool returns incomplete tasks with related subtasks/sidequests, which is useful context beyond annotations. However, it does not clarify whether the subtasks/sidequests are embedded or returned separately, leaving some ambiguity.
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, concise sentence that is front-loaded with the key action and resource. While it could include more detail, it avoids unnecessary verbosity.
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 absence of an output schema, the description partially explains what is returned ('open tasks with related subtasks/sidequests') but does not specify the response structure or format. For a simple getter with annotations, it is minimally complete but not thorough.
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%, so the parameter descriptions in the schema already cover both parameters. The description does not add additional meaning or syntax hints for the parameters; it only describes the overall output.
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 ('Get'), the resource ('open tasks for a milestone'), and the inclusion of related entities ('with related subtasks/sidequests'). This distinguishes it from sibling tools like 'get_tasks_by_milestone' (likely all tasks) and 'get_incomplete_tasks' (without milestone filter).
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?
The description provides no explicit guidance on when to use this tool versus alternatives such as 'get_tasks_by_milestone' or 'get_incomplete_tasks'. It lacks information about prerequisites or exclusions, leaving the agent to infer usage solely from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering safety and idempotency. The description adds that results include 'field names and types', which is consistent but adds minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous content, making it efficient and front-loaded.
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 tool with complete annotations and schema, the description is adequate. It specifies the output (field names and types) but lacks examples or context about settings tables, which would enhance completeness.
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 description does not add meaning beyond what the parameter 'table' description already provides. 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 tool retrieves field names and types for a specific table, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like get_core_fields or get_project_fields, which also retrieve field info from other contexts.
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?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools for different field retrieval contexts, the absence of usage context limits agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's 'Get available fields' is consistent. No additional behavioral details are provided beyond the purpose (e.g., side effects, performance, error handling). The description adds little value beyond annotations, making a score of 3 appropriate.
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, well-structured sentence that front-loads the verb and resource. Every word contributes to the purpose, with no redundant or missing information. It 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and the description does not clarify the return format (e.g., list of strings, map of field names to types). Given many sibling tools that provide similar functionality from different contexts (e.g., get_settings_fields, get_project_json_parameters), the description could be more complete by stating what 'available fields' means or which tables are valid. The current brevity leaves gaps for an agent to resolve.
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 sole parameter 'table' is described in the schema as 'Table name to get available fields for', which already provides clear semantics. The description does not add extra meaning or constraints (e.g., acceptable table names, case sensitivity), and with 100% schema coverage, a baseline of 3 is justified.
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?
Description clearly states the action (get) and resource (available fields for table) and hints at usage context (generic add/update operations). It distinguishes itself from sibling tools like get_settings_fields and get_project_json_parameters by specifying 'table' and 'add/update operations', though could be more precise about 'available fields'.
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 tool is used to retrieve fields for add/update operations, providing context for when to use it. However, there is no explicit guidance on when not to use it or comparison with similar siblings (e.g., get_project_json_parameters, get_user_custom_json_parameters), leaving the agent to infer without clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool's safety profile is clear. The description adds no further behavioral details (e.g., no mention of pagination or return format).
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?
Extremely concise single sentence with no unnecessary words. It is front-loaded and clear, though perhaps too minimal for some contexts.
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 retrieval tool with one parameter and no output schema, the description is adequate but could be improved by indicating the return type (e.g., list of theme objects). It lacks completeness compared to richer descriptions.
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% (flow_id parameter documented). The description does not add meaning beyond the schema's 'Flow ID' label. 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 action (get), resource (themes), and scope (for a flow). It distinguishes from sibling tools like get_all_themes (no filter) and get_flows_for_theme (inverse relation).
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 on when to use this tool vs alternatives such as get_all_themes or get_theme_by_name. The description does not provide any context or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate these. The description adds no additional behavioral context (e.g., pagination, result limits), but given annotations, it meets the baseline.
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, efficient sentence that front-loads the purpose and includes the key requirement. It is appropriately concise with no redundant content.
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 output schema, the description lacks information about return format or result size. It also does not differentiate from sibling search tools beyond the filter requirement. However, the input schema is fully covered, and annotations provide safety context, making it minimally sufficient.
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 all five parameters well-described (e.g., 'LIKE match, case-insensitive' for name). The tool description adds no extra parameter meaning, so 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 tool searches user directives with optional filters, distinguishing it from sibling tools like get_all_directives (no filters) and get_directive_by_name (exact match). However, it does not specify what 'user directives' are, leaving some ambiguity.
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 includes a usage requirement ('At least one filter required'), which helps guide invocation. It does not provide explicit guidance on when to use this tool versus other search tools (e.g., search_directives) or when not to use it, limiting decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the description correctly implies mutation without destruction. However, the description does not add behavioral details beyond the basic action, such as whether duplicates are allowed, if dependencies are additive, or any side effects. With annotations already providing safety profile, the description provides adequate but not exceptional 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?
The description is extremely concise, two sentences that immediately state the purpose and provide context. Every word is meaningful; no filler. It is front-loaded with the key verb and resource.
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's simplicity (3 required params, no output schema, no nested objects) and the presence of annotations, the description is mostly complete. However, it does not mention return behavior (e.g., confirmation or error handling) nor does it distinguish from the similar add_interactions tool. This is a moderate gap for an AI that must choose among many similar tools.
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?
Input schema covers 100% of parameters with descriptions. The description adds the context that source/target are function names and lists the possible interaction_type values, which the schema already does. The additional value is marginal, 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 tool records a dependency between two functions by name, listing the interaction types (call, chain, borrow, compose, pipe). It distinguishes itself from siblings like delete_interaction and update_interaction, though it doesn't explicitly differentiate from add_interactions (plural). The verb 'record' combined with the resource 'dependency' makes 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like add_interactions (plural). It does not mention prerequisites, when not to use it, or the context in which it is appropriate. The agent is left to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the destructiveHint annotation and adds behavioral context such as 'item validation' and consistency with delete_task's logic. It does not contradict annotations and provides extra insight beyond the structured fields.
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, front-loaded sentence with no unnecessary words. It efficiently communicates the tool's purpose and key behavior.
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 destructive tool, the description is adequate but lacks explicit warnings about irreversibility or details about return values. The 'item validation' reference adds some completeness, but overall it could be more thorough.
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 description adds no new meaning to parameters beyond what the schema already provides. Baseline score of 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 'Delete' and the resource 'sidequest'. It adds context with 'item validation' and references 'same logic as delete_task', which helps distinguish it among many sibling delete tools, though it could be more explicit about what the validation entails.
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 on when to use this tool vs alternatives like delete_task, delete_subtask, etc. The description only references delete_task's logic but does not provide explicit context for selection or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey destructiveHint=true and readOnlyHint=false. The description adds no additional behavioral context beyond the fact it deletes. No mention of side effects, permanence, or permissions is provided.
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 conveys the core action without extraneous information. It is efficiently front-loaded and 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?
For a simple delete operation with two parameters and no output schema, the description is minimally adequate. However, it lacks context on what happens upon successful deletion, error scenarios (e.g., non-existent record), and any referential integrity implications.
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 adequately describes the two parameters. The description does not add extra meaning, such as examples or further qualification of what constitutes a 'record_id'.
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 'Delete entry from user_directives.db table', which precisely matches the tool name and specifies the target resource. It is distinct from sibling delete tools for other entities.
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 provided on when to use this tool versus alternatives like delete_file or delete_flow. It does not mention prerequisites, such as existence of the record, or when to avoid deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds context about caching and being a special orchestrator, which hints at internal usage but does not provide significant behavioral detail beyond that.
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 with no unnecessary words. It is front-loaded and efficiently communicates the core purpose.
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 tool has no parameters and no output schema, the description provides enough context for a simple load-all operation. The mention of 'for caching (special orchestrator)' adds operational context. However, it could clarify what 'directives' are relative to the domain.
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?
There are zero parameters, so the description does not need to add meaning. The schema coverage is 100% (vacuously). Baseline for no parameters is 4; the description is adequate.
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 states 'Load all directives for caching (special orchestrator)', specifying the action (load all), the resource (directives), and the context (caching, orchestrator). It is clear but does not differentiate from sibling tools like get_all_directive_keywords or get_all_directive_names, which also load subsets of directives.
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 on when to use this tool versus alternatives such as get_directive_by_name or search_directives. It does not mention when it is appropriate or inappropriate to use, nor any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety traits. It adds the scope 'all directives in a category,' which is helpful but doesn't disclose additional behaviors like error handling or response format. This is adequate but minimal beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of five words—extremely concise with no extraneous information. It front-loads the action and resource, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema, annotations present), the description provides minimal context. It doesn't mention return format, behavior on missing categories, or integration with related tools. Adequate but could be more complete for a new agent.
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% (only parameter 'category_name' described as 'Category name'). The description adds no extra meaning about the parameter, such as format, allowed values, or case sensitivity. Baseline 3 is appropriate since the schema does the work.
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 'Get all directives in a category' clearly states the action (get) and the resource (directives), specifying the grouping (by category). It distinguishes from siblings like get_all_directives (unfiltered) and get_directive_by_name (specific name), making the tool's 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_directives_by_type, search_directives, or get_all_directives. With many sibling tools, some contextual advice (e.g., 'Use when you need directives for a specific category') would significantly aid the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's claim of 'get' is consistent. It adds that functions are embedded, which is useful behavioral context beyond annotations. However, it does not disclose potential limitations like pagination or sorting.
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, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.
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's simplicity (one parameter, no output schema), the description is adequate but could be more complete by mentioning the return format or any ordering/defaults. The annotations cover behavioral safety, so the main gap is output expectations.
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 schema already provides a clear description of the 'flow_id' parameter. The description does not add any additional meaning or formatting details 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', the resource 'all files for a flow', and adds specific detail 'with functions embedded in each file dict'. This distinguishes it from the sibling tool 'get_files_by_flow', which likely returns files without embedded functions.
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 explicit guidance on when to use this tool vs alternatives or when not to use it. There is no mention of prerequisites or context where this tool would be inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating safe, repeatable behavior. The description adds no further behavioral context, such as the format or structure of the returned incomplete subtasks. Given the annotation coverage, a score of 3 is appropriate; no contradiction, but the description does not enhance 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?
The description is a single, clear sentence of 6 words with no redundancy. It is front-loaded and every word serves a purpose.
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 absence of an output schema, the description should ideally explain what is returned (e.g., a list of subtask objects, what fields they contain, or how 'incomplete' is defined). The current description lacks this information, leaving the agent uncertain about the return structure. However, the simplicity of the tool (single parameter, read-only) and annotations partially compensate.
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% with a single parameter 'task_id' described as 'Task ID'. The description does not add any additional meaning or constraints beyond what the schema provides, 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 'Get incomplete subtasks for specific task' clearly identifies the verb (get), resource (incomplete subtasks), and scope (for a specific task using task_id). This distinguishes it from sibling tools like 'get_incomplete_subtasks' (all incomplete subtasks) and 'get_subtasks_by_task' (all subtasks for a task).
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 explicit guidance on when to use this tool versus alternatives. For example, it does not advise using this tool over 'get_subtasks_by_task' when only incomplete subtasks are needed, or to prefer 'get_incomplete_subtasks' when task_id is not available. The decision is left to inference from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. Description adds no additional behavioral context, but doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, efficient sentence with no fluff. Perfectly 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 read-only tool with no parameters or output schema, the description is mostly sufficient. Could be improved by noting what type of tables (user-defined?) but acceptable.
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?
No parameters exist, so the description doesn't need to add parameter info. Baseline 4 given zero parameters.
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?
Description clearly states it lists tables in the project database. However, there are sibling tools like get_core_tables, get_settings_tables, and get_user_custom_tables that list tables in other databases, so it could be confused without differentiation.
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 on when to use this tool vs siblings. With many table-listing siblings, explicit context is needed but missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, providing basic safety info. The description adds minimal extra behavior, but is consistent and sufficient for this simple read 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 a single, front-loaded sentence with no wasted words. Every word is necessary and informative.
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 zero parameters and no output schema, the description is mostly complete. It could mention the return type (list of table names) for extra clarity, but it is adequate.
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?
No parameters exist, so the baseline is 4. The description does not need to add parameter info, and schema coverage is 100%.
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 verb 'List' and resource 'all tables in user settings database', distinguishing it from siblings like get_settings_fields or get_user_custom_tables. However, it does not explicitly differentiate from similar tools.
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 provided on when to use this tool versus alternatives. The description lacks context for selection among many get-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true, indicating safe read-only behavior. The description adds context about architectural flow IDs and the connection to codebase navigation, but does not disclose further behavioral traits (e.g., no mention of result format or pagination). With strong annotations, the description is adequate but not exceptional.
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?
Two sentences, each with distinct value: first states the action and output, second explains usage. No wasted words. The description is front-loaded 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 tool with one parameter and no output schema, the description adequately covers purpose and usage context. Combined with annotations and high schema coverage, the information is complete enough for correct invocation. No additional information (e.g., return format) is strictly necessary given the tool's simplicity.
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 single parameter 'task_id' is already fully described in the schema (100% coverage). The description mentions task in the context sentence but adds no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate given full schema coverage.
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 ('Get the architectural flow IDs for a task') and explains the purpose ('understand which part of the codebase a task touches and find relevant files'). It distinguishes from sibling tools that focus on files or directives rather than tasks, but lacks explicit differentiation from closely related flow-retrieval tools.
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 context ('Use to understand which part of the codebase a task touches') but does not provide explicit when-not-to-use guidance or list alternative tools. With many sibling flow tools (e.g., get_flows_for_file, get_directive_flows), a mention of exclusions would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds no additional behavioral context but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words, front-loaded with verb and resource. Extremely concise with no wasted words.
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?
Simple tool with no input/output schema; the description adequately conveys the purpose. Could mention output format, but not critical.
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?
No parameters exist, so schema coverage is 100%. The description provides no parameter info, which is acceptable given zero parameters.
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 it retrieves the complete schema SQL for the user directives database, which is specific. However, it does not differentiate from sibling tools like get_project_schema or get_core_schema.
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 on when to use this tool versus alternatives. There is no context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set idempotentHint=true and destructiveHint=false, so the description does not contradict them. However, it adds minimal context beyond stating the table name. No new behavioral traits are disclosed.
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, concise sentence without unnecessary words. It is appropriately sized for a simple update tool.
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 tool's simplicity (one parameter, no output schema, annotations present), the description covers the essential purpose. However, it could be slightly more informative about the effect or validation.
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% with a single parameter described as 'New source directory path'. The description does not add any further meaning, so it meets 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 clearly states the action (update), the resource (source directory), and the location (infrastructure table). It distinguishes from sibling tools like get_source_directory (read) and other update tools by specifying the exact resource.
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 provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, indicating a mutation but no destruction. The description adds that it creates an item, which aligns, but does not disclose side effects, permissions needed, or return behavior. Since annotations are minimal, the description should provide more context about what happens after creation.
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 of clear, concise language. It front-loads the purpose immediately and provides essential context without any redundant or verbose content. Every word contributes to understanding.
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 five parameters with full schema coverage, no output schema, and minimal annotations, the description provides adequate context for a creation tool. It explains what items are and where they belong. However, it could be slightly improved by mentioning that the tool returns the created item or its ID, but it is still fairly 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?
All five parameters have schema descriptions (100% coverage), so the schema already documents their purpose. The description adds context by explaining that reference_table and reference_id refer to parent entities (task, subtask, sidequest), but this is implicit from the parameter descriptions. The description does not significantly enhance parameter understanding 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 'Create a single work item under a task, subtask, or sidequest', specifying the exact action and the parent entities. It also defines items as 'the smallest trackable units of work', distinguishing them from larger structures like tasks or subtasks, which are handled by sibling tools like add_task or add_subtask.
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 the tool (to create a smallest work unit under a parent) but does not explicitly state when not to use it or mention alternatives. For example, it does not clarify that add_items (plural) might be used for batch operations, or that this tool is for single additions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, destructiveHint=false, idempotentHint=false. Description states creation but does not disclose side effects like overwrite behavior, permissions needs, rate limits, or error conditions for existing modules.
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 concise sentences, front-loaded with purpose, efficient use of words.
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?
Lacks return value description and handling of duplicate module names. With 5 parameters and no output schema, more detail on behavior is needed for completeness.
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%, each parameter well-described. Description adds context about file assignment and external_dependencies, but value is marginal beyond 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 tool creates a new module as a reusable code boundary, distinguishes from sibling add_file_to_module by noting files are assigned explicitly via that tool, and mentions external_dependencies for wrapped libraries.
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?
Provides guidance on module-directory mapping, explicit file assignment via add_file_to_module, and use of external_dependencies. Does not explicitly exclude scenarios, but context is clear compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds no further behavioral context, such as what happens if a duplicate key is provided (schema says unique, but behavior not described). Adequate but not enriched beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no superfluous words. Efficiently conveys the core action.
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 description covers the basic operation but omits details like uniqueness constraint behavior and what the default scope is. However, given the simple schema and no output schema, it is mostly 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 coverage is 100% with each parameter having a description. The description adds no extra meaning beyond the schema. 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 'Add', the resource 'project-wide user setting', and the target table 'user_settings'. It distinguishes this tool from sibling tools that add other entities like 'add_settings_entry' or 'add_user_custom_entry'.
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 on when to use this tool versus alternatives such as 'add_settings_entry' or 'add_user_custom_entry'. The description lacks context on when this specific tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds method details (using Git or filesystem timestamp) beyond the readOnlyHint and idempotentHint annotations. However, it does not specify the return type or what 'changed' means (e.g., boolean vs details), leaving behavioral ambiguity.
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, direct sentence that front-loads the purpose. Every word is informative with no redundancy. It is optimally concise.
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?
For a tool with no output schema, the description should explain the return value (e.g., boolean) or provide more detail on what constitutes a change. Its absence leaves the tool under-specified for an AI agent to interpret results 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 parameter blueprint_path already has a full description in the schema (100% coverage). The tool description adds no additional semantic for the parameter beyond what the schema provides, hence baseline 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 clearly states the tool checks if ProjectBlueprint.md has changed, specifying the methods (Git or filesystem timestamp). It is specific to the blueprint file, distinguishing it from sibling tools like file_has_changed.
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 for checking blueprint changes but does not explicitly provide guidance on when to use this tool versus alternatives like file_has_changed or detect_external_changes. No when-not-to-use or alternative names mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds that it creates a database from SQL schema, but does not elaborate on behavioral traits like permission needs, side effects, or whether existing databases are overwritten. With annotations present, the description provides modest added context.
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 consists of two sentences, both front-loaded with the core action. The second sentence adds useful context without excess verbiage. 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?
Given low complexity (1 param, no output schema, annotations present), the description is adequate but not exhaustive. It mentions SQL schema but does not specify prerequisites or behavior if the database already exists. The 'FP-compliant replacement' aids context, but some completeness gaps remain.
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% with a single parameter fully described. The description does not add any meaning beyond what the schema already provides for 'source_directory'. 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 it creates a per-project state database from an SQL schema, using specific verb and resource. It distinguishes itself by mentioning 'FP-compliant replacement for mutable global variables', setting it apart from sibling tools like 'update_project_state' or 'query_project_state'.
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 context (FP-compliant state management) but does not explicitly state when to use this tool versus alternatives. No when-not or direct comparisons are provided, leaving the agent to infer use cases from the 'FP-compliant replacement' hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive, but the description adds no details about the finalization process (e.g., validation, naming checks, state transitions). The term 'finalize' alone does not disclose behavioral traits beyond what annotations already imply.
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, concise sentence with no extraneous information. It conveys the essential purpose efficiently.
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 description lacks details on return values, prerequisites (e.g., type must be in reserved state), validation behavior, or expected output. Given no output schema and a complex set of parameters including nested objects, the description is incomplete for guiding 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 each parameter is adequately described in the schema. The tool description adds only high-level context without enhancing parameter meaning, meeting baseline expectation.
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 'Finalize reserved type after creation' clearly specifies the action (finalize) and resource (reserved type), distinguishing it from sibling tools like 'reserve_type' (which creates the reservation) and 'finalize_types' (batch version).
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 'after creation', providing a clear usage context. While it does not mention alternatives or when not to use, the sibling tool list and the context of a two-step process (reserve then finalize) make the usage fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds 'for a specific table' but no extra behavioral context (e.g., what happens if table doesn't exist, return format). With annotations covering safety, a 3 is baseline.
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?
Single sentence, front-loaded with purpose. No unnecessary words. Highly 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 getter with one param and annotations covering safety, the description is complete enough. Could mention output format since no output schema, but not critical. Sibling context and schema/annotations fill gaps.
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% with one parameter 'table' described. Description merely reinforces 'for a specific table' without adding new meaning. Baseline 3 as per guidelines.
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 clearly states 'Get field names and types for a specific table' - a specific verb and resource that distinctively identifies its purpose among siblings like get_core_tables (gets table names) and get_core_schema (gets full schema).
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 on when to use this vs alternatives. Does not mention that for table names, use get_core_tables, or for full schema, use get_core_schema. No when-not or prerequisite info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint (true) and idempotentHint (true), so the description does not need to cover these. However, the description adds no additional behavioral context beyond what annotations provide, such as performance considerations or response structure.
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 wasted words. It is appropriately sized for a simple lookup tool, though additional context could be included without harming conciseness.
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 1-parameter read-only tool with no output schema, the description is adequate but lacks details on what the returned directives look like (e.g., names, objects) and any pagination or ordering behavior. Annotations cover safety, so the description is minimally 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?
The input schema has 100% description coverage for the only parameter 'helper_name' (described as 'Helper name'). The description adds no further meaning beyond the schema, so 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's purpose: 'Get all directives that use a helper (reciprocal lookup)'. It uses a specific verb 'Get' and identifies the resource 'directives that use a helper', distinguishing it from sibling tools like 'get_directive_by_name' or 'get_helpers_for_directive'.
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?
Usage is implied as a reciprocal lookup, but there is no explicit guidance on when to use this tool versus alternatives like 'get_directive_by_name' or 'get_directives_by_category'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description does not add any behavioral context beyond this, such as permissions or response format. It neither contradicts nor significantly enhances 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?
The description is a single, concise sentence that immediately conveys the tool's function. It is front-loaded with essential information and contains no unnecessary words.
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 tool's simplicity (one parameter, no output schema) and adequate annotations, the description sufficiently covers what is needed. It could include the return format, but not required for basic understanding.
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?
With 100% schema coverage, the description adds no extra meaning beyond the schema's 'Theme ID' for the single parameter. Baseline 3 is appropriate as the schema already documents the parameter fully.
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' and the resource 'all flows for a theme', which precisely defines the tool's purpose. It effectively distinguishes itself from sibling tools like 'get_flows_for_file' and 'get_themes_for_flow'.
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?
The description provides no guidance on when to use this tool versus alternatives. Among many 'get_flows_*' siblings, no context is given for selection, leaving the agent to infer usage solely from the tool name and parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds no behavioral context beyond the purpose, so it meets the baseline but does not exceed it.
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, concise sentence with no wasted words. It is front-loaded with the primary action.
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 retrieval tool with one parameter and no output schema, the description is largely sufficient. Could optionally mention that it returns a list of milestones, but not strictly necessary.
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 has 100% description coverage for the single parameter. The tool description adds no additional meaning to the parameter beyond what is in the schema, so 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 clearly states the action 'Get all milestones' and the resource 'for a completion path', distinguishing it from sibling tools like get_milestones_by_status.
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 on when to use this tool versus alternatives (e.g., get_milestones_by_status, get_incomplete_milestones). The description only states what it does, not when or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to reiterate safety. It adds no further behavioral context (e.g., ordering, pagination). No contradiction.
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 wasted words, front-loaded with the core purpose. Efficient and clear.
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 simple nature (1 parameter, no output schema), the description is adequate. It could be slightly more specific about what is returned, but it suffices.
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%; the description does not add extra meaning beyond the schema's parameter description. 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 verb 'Get' and resource 'milestones' with a filter by 'status'. It distinguishes from siblings like 'get_milestones_by_path'.
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 on when to use this tool versus other milestone retrieval tools such as 'get_incomplete_milestones' or 'get_milestones_by_path'. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is clear. The description adds value by specifying the use of the module_files junction and aggregation, but it does not provide additional behavioral details such as potential side effects (none expected) or response size limits.
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 with three sentences, each adding information. It is front-loaded with the core purpose and efficiently explains the mechanism and output. No wasted words.
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 largely complete: it states what it does, how it works, and what it returns. It could be slightly more precise about the scope (e.g., whether it works for all modules or only those with dependencies), but overall it provides sufficient context.
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 has 100% coverage for the single parameter (module_id), so the description need not add much. The description does not elaborate on the parameter beyond what the schema provides, but the schema itself is clear.
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 purpose: 'Get cross-module dependencies' and explains the mechanism ('via module_files junction') and output ('aggregated counts per target module'). It distinguishes from sibling tools like get_module_files or get_module_functions by focusing on cross-module interactions.
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?
The description lacks any guidance on when to use this tool versus alternatives. With many sibling tools, it would be helpful to know, for example, to use this for dependency analysis rather than for listing module contents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true, signaling safe, repeatable behavior. The description adds no further behavioral context (e.g., authorization or rate limits), but does not contradict annotations. A score of 3 reflects adequate transparency given the annotation coverage.
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?
Single sentence, no unnecessary words. Efficiently conveys the core action and target. 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?
With one parameter and annotations present, the description is mostly complete for a simple metadata retrieval tool. However, without an output schema, it would benefit from briefly stating the return format (e.g., 'returns a list of field names and types'). Slight gap, but adequate overall.
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% (one parameter with description 'Table name to get fields for'). The tool description adds no additional meaning beyond what the schema provides, so 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?
Description uses verb 'get' and resource 'field names and types for a specific table', clearly indicating retrieval of table metadata. The tool name 'get_project_fields' and the parameter 'table' reinforce this. While similar siblings exist (e.g., get_core_fields), the description's specificity to 'a specific table' distinguishes it adequately.
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 on when to use this tool versus alternatives like get_core_fields, get_settings_fields, or get_project_schema. The description merely states the function without contextualizing its appropriate application.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds no additional behavioral details beyond implying return of fields. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no superfluous words, and the key information is front-loaded. 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?
Given the tool's simplicity (single parameter, no output schema, and annotations present), the description is sufficient. It explains the purpose and usage context, though it could mention what the output looks like.
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 description does not add meaning beyond what the schema already provides for the 'table' parameter. The description reinforces the parameter's purpose but adds no new semantics.
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 tool gets available fields for a table to be used with generic add/update operations. This is specific enough, but 'fields' might be ambiguous without further context. Given the sibling tools, it distinguishes itself by focusing on project json parameters.
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 implicitly suggests when to use this tool (before performing generic add/update operations on a table), but does not explicitly state when not to use it or compare to alternatives like get_project_fields or get_project_schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it 'parses schema' but does not disclose additional behavioral traits beyond what annotations provide. No contradiction.
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 wasted words. It efficiently conveys the tool's purpose and method.
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 tool with two simple parameters and no output schema, the description adequately explains what it returns and how it works. It could be more explicit about the database scope but is sufficient.
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% with both table and field parameters described. The description does not add meaning beyond the schema, so baseline of 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 tool returns allowed values for CHECK constraint enum fields in project.db. It specifies the verb 'Returns' and the resource. However, it does not explicitly distinguish from similar sibling tools like core_allowed_check_constraints, though mentioning project.db helps.
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 for querying CHECK constraints but does not provide explicit guidance on when to use this tool versus alternatives. No when-not-to-use or comparison to sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are all false, so they provide no behavioral clues. The description adds the critical detail that 'null fields make functions invisible to future sessions', which is valuable behavioral information beyond the schema. However, it does not disclose other potential behaviors like reversibility, side effects, or permission requirements.
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 long, front-loading the core purpose in the first sentence and adding a critical behavioral note in the second. Every sentence earns its place with no wasted words.
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?
Given the tool's complexity (6 parameters, nested objects, no output schema, and numerous sibling tools), the description is too brief. It lacks guidance on error conditions, return value expectations, or how this tool relates to siblings like 'reserve_functions' or 'finalize_function'. The description is incomplete for an agent to fully understand the tool's role and constraints.
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%, meaning all 6 parameters have descriptions in the schema. The description reiterates the importance of 'purpose, parameters, and returns' but does not add new semantic meaning beyond what the schema already provides. The baseline is 3 due to 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 action ('Reserve a function ID') and the resource ('function'), with specific instructions on including 'purpose, parameters, and returns'. It effectively distinguishes from sibling tools like 'reserve_file' and 'reserve_type' by specifying 'function'.
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 mentions 'before writing code', implying a temporal usage context. However, it does not provide explicit guidance on when to use this tool versus alternatives like 'reserve_functions' for batch operations, nor does it state when not to use it. The usage context is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds that 'null fields force full file reads in future sessions,' which provides additional behavioral context. However, it does not disclose other potential side effects (e.g., database record creation, ID reservation mechanics) beyond the schema and 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 a single, front-loaded sentence that efficiently conveys the core action and a key behavioral warning. No superfluous words.
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?
Given the tool has 6 parameters, 2 required, a nested object, and no output schema, the description is too brief. It fails to explain what the tool returns (e.g., reserved ID), how to use the reserved ID in subsequent steps, or any error conditions. This leaves the agent without sufficient context to use the tool correctly in a multi-step workflow.
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 input schema already describes all parameters. The description does not add any new semantic meaning beyond what the schema provides, meeting the baseline expectation for this dimension.
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 purpose: 'Reserve a type ID before writing the definition.' It uses a specific verb ('reserve') and resource ('type ID'), and distinguishes from sibling tools like reserve_function and reserve_file by focusing on type definition preparation.
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 advises to 'Include definition_json and description' and warns about null fields, providing some usage context. However, it does not specify when to prefer this tool over alternatives like reserve_types or add_types_functions, nor does it explain prerequisites or subsequent steps beyond writing the definition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds value by mentioning it 'gathers data from multiple tables', implying a potentially expensive operation. However, it does not disclose further behavioral traits such as performance impact or rate limits.
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 front-load the purpose without redundancy. Every word earns its place, making it easy to parse quickly.
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?
While the description captures the high-level purpose, it lacks detail on the return format or content. Given no output schema, the agent would benefit from knowing what 'comprehensive project state' includes (e.g., list of tables, aggregated summaries). This gap makes it somewhat incomplete.
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% with the sole parameter 'type' fully described (three levels, default). The description adds no additional meaning beyond what the schema provides, so 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?
Description clearly states it 'retrieves comprehensive project state' and acts as an 'orchestrator' gathering data from multiple tables. This distinguishes it from sibling tools that retrieve specific data (e.g., get_project, get_settings). The verb 'retrieves' and resource 'comprehensive project state' are specific and non-tautological.
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 context ('for AI to determine next steps') but does not explicitly state when to use this orchestrated status versus individual getter tools. No exclusions or alternatives are mentioned, leaving the agent to infer without clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description echoes the deletion behavior but adds no additional context (e.g., cascade effects, permanence). With annotations present, the minimal description is adequate.
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?
Single sentence of 5 words is extremely concise and front-loaded, containing only the essential information without any fluff.
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 simple parameters and no output schema, the description is minimally complete. However, it lacks information about validation (e.g., whether the table/record must exist) and permanence of the deletion.
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 fully documents both parameters (table and record_id). The description adds no extra semantic information beyond what the input schema provides.
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 'Delete entry from user_preferences.db table', which clearly identifies the action (delete) and resource (settings entry). It distinguishes from sibling tools like add_settings_entry and update_settings_entry.
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 deleting settings entries but provides no explicit guidance on when to use this tool versus other delete tools (e.g., delete_project_entry) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint) already cover safety and idempotency. The description adds no behavioral context beyond the name, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste. Perfectly concise for the simplicity of the 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?
While adequate for a read-only tool with no inputs and annotations, the description does not explain the return format or structure, which would be helpful since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Baseline score of 4 applies; the description correctly implies no input 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?
Description clearly states 'Get all directive categories' with specific verb and resource. This distinguishes it from sibling tools like get_all_directives, get_directives_by_category, etc.
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?
No explicit guidance on when to use this tool versus alternatives, but the purpose is self-evident for a simple read-only operation. Could be improved by noting that it's the canonical way to list all categories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds no new behavioral context. It correctly doesn't contradict the annotations, but adds minimal value beyond them.
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, efficient sentence with no wasted words. Perfectly concise.
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 simple, parameterless list tool with annotations covering safety, the description is complete. It tells what the tool does without needing more.
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?
No parameters exist. Schema description coverage is 100% (vacuously). The description does not add parameter info, so baseline 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 clearly states the verb 'List' and the resource 'all tables in core database'. It is specific and distinguishes from siblings like get_databases and get_project_tables.
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 on when to use this tool versus alternatives. With many sibling tools, explicit context would help, but it's lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description need not restate them. The description does not add behavioral context beyond the annotations, but it also does not contradict them.
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, six-word sentence that is direct and devoid of unnecessary words. It effectively communicates the tool's purpose in minimal space.
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?
Given the tool's simplicity (one required parameter, read-only, idempotent), the description is complete. No output schema is present, but the return value is straightforward and well-understood from context.
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 parameter 'file_id' is described in the schema. The description adds no additional meaning beyond what the schema already provides, so 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 'Get all flows for a file' clearly states the action (get), object (flows), and scope (for a file). It is specific and distinguishes itself from sibling tools like get_files_by_flow or get_flows_for_theme.
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 provided on when to use this tool vs alternatives such as get_files_by_flow or get_flows_for_theme. The agent receives no context about prerequisites or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds value by clarifying the filtering behavior ('flexible filtering with structured JSON conditions'). However, it does not disclose details like whether conditions support complex operators or what happens when no rows match.
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 of 12 words, front-loading the key information. It is concise without wasted words.
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 2-parameter read-only tool with good annotations, the description is adequate but lacks details on return format, error handling, or empty results. With nested objects, additional context on the conditions structure would be helpful.
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% (both parameters documented), so baseline is 3. The description mentions 'structured JSON conditions' but does not go beyond the schema to explain the format or allowed operators for the 'conditions' object.
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 performs 'Flexible filtering' on 'user_directives.db tables' using 'structured JSON conditions'. It uses the verb 'get' and specifies the resource (user_directives.db), distinguishing it from sibling tools like 'get_from_user_custom' which likely returns all rows.
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 for filtered queries but does not explicitly state when to use this tool over alternatives like 'get_from_user_custom' or 'query_user_custom'. It lacks guidance on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that the tool retrieves all interactions for a function in both directions, which is useful but does not elaborate on return format, pagination, or other behavioral traits. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a dash for additional context. No wasted words; every word contributes to understanding the tool's purpose.
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?
While the tool is simple with one parameter and readOnly behavior, the lack of output schema means the agent needs to infer the return structure. The description mentions 'trace dependency graphs' but does not specify what interactions look like, which is a gap in completeness.
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 single parameter 'function_name' is described in the schema with a clear description. The description adds no additional meaning beyond what the schema provides, resulting in baseline score.
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 ('Get all interactions'), the resource ('for a function'), and the scope ('both as source and target') with a specific purpose ('trace dependency graphs'). It effectively distinguishes this tool from similar siblings like get_interactions_by_file.
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 for dependency graph tracing but does not explicitly state when to use this tool versus alternatives (e.g., get_interactions_by_file). No when-not or exclusion criteria are provided, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds 'all' implying complete retrieval, but no further behavioral context (e.g., return format, side effects). With annotations covering the main behavioral traits, description adds minimal extra value.
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?
Single sentence of 4 words, no filler. Front-loaded and efficient.
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 no output schema and low complexity, description is adequate but could clarify what 'tracking feature flags' are or what the return structure looks like. Minimal completeness for an agent to use effectively.
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?
Zero parameters, schema coverage 100%. Description does not need to add parameter details; baseline for no-parameter tools is 4.
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 clearly states 'Get all tracking feature flags', which is a specific verb+resource combination. It distinguishes from siblings like 'toggle_tracking_feature' (write) and other 'get_*' tools that 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'get_user_settings' for user-specific settings). Lacks when-not or context for selection among many 'get_*' siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, ensuring safety. The description adds that it retrieves 'field names and types', clarifying the return content beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, conveying the essential information efficiently.
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 simple with one parameter, but the description lacks specifics about the output format (e.g., list, object) and error handling. Annotations mitigate safety concerns, but some behavioral context is missing.
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 documentation covers the single parameter 'table' with a clear description. The tool description adds no new semantic detail about the parameter, so it meets the baseline for high 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 'Get field names and types' with a specific resource ('specific table in user_directives.db'), which distinguishes it from sibling tools like get_core_fields or get_settings_fields that target other databases.
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 provided on when to use this tool versus alternatives. Given many sibling get_* tools, explicit context or exclusions would help, but the description only states its function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds no behavioral context beyond what is in annotations, but it does not contradict them. With annotations covering core traits, a 3 is appropriate for not adding extra value.
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 no extraneous information. Front-loaded with verb and resource. Efficient and clear.
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 simple, read-only lookup with one parameter and strong annotations, the description is complete. No output schema is needed given the straightforward retrieval. All essential information is present.
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 sole parameter (name) is fully described in the schema (100% coverage). The description reiterates 'unique name' but adds no additional meaning (e.g., format, case sensitivity). Baseline 3 is correct when 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 verb (Get), resource (user directive), and method (by unique name). It distinguishes from siblings like get_directive_by_name (presumably non-user) and other get_ tools.
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 usage guidance is provided. The description does not indicate when to use this tool over alternatives like get_directive_by_name or other get_ functions. The agent must infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's additional context (database source, AND logic, no-filters behavior) is useful but not extensive. It does not disclose pagination, ordering, or return format, but the safety profile 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that are front-loaded with essential information. Every sentence adds value: it states the action, the database, the filter logic, and the default behavior. No unnecessary words.
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?
Without an output schema, the description does not explain return values, pagination beyond the 'limit' default, or ordering. For a simple read tool with 7 parameters, it provides the core functionality but misses details that could help the agent understand the full result structure.
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% with each parameter having a description. The description only summarizes 'optional filters' without adding extra meaning beyond what the schema provides. Baseline 3 is appropriate given high 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 verb ('Get'), resource ('notes from user_directives.db'), and behavior ('with optional filters'). It distinguishes from siblings like 'search_user_directive_notes' and 'get_notes_comprehensive' by specifying the database and filtering logic.
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 explains that filters use AND logic and that no filters returns all notes, but it does not explicitly guide when to use this tool versus alternatives like 'search_user_directive_notes' or 'get_notes_comprehensive'. No when-not or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds that it executes a complex SQL WHERE clause, hinting at raw SQL-like behavior, but does not disclose specifics like potential performance implications or permission requirements beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with key information ('Execute complex SQL WHERE clause') and immediately qualifies its usage ('advanced, rare use'). No unnecessary words.
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?
With 100% parameter coverage and no output schema, the description is minimally adequate. However, it lacks explanation of what the tool returns (likely query results) and does not contrast with similar query tools among siblings, leaving the agent to infer usage scenarios.
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 already explains the 'query' parameter as a 'WHERE clause without "WHERE" keyword'. The description adds no new semantic information beyond confirming the tool's purpose.
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 executes a 'complex SQL WHERE clause' on the project database, specifying it is 'advanced, rare use'. This distinguishes it from sibling tools like get_from_project or query_core which are simpler queries.
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 advanced, rare cases via 'advanced, rare use', but does not explicitly state when to use it versus alternatives or when not to use it. More guidance on preferring simpler query tools would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it is safe and idempotent. The description adds that it uses FTS5 full-text search with relevance ranking, but no additional behavioral details such as pagination or result limits are disclosed.
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 concise sentence with no redundant information. It front-loads the core purpose and key features (FTS5, relevance ranking), earning every word.
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 search tool with good annotations and schema, the description is minimally adequate. However, it lacks details about return format, pagination, or error handling, which would improve completeness.
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 adequately. The description restates the FTS5 aspect but adds no extra meaning beyond what the schema provides. 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 searches tracked types using FTS5 full-text search with relevance ranking. It uses a specific verb and resource, distinguishing it from sibling search tools for directives, functions, modules, notes, etc.
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 for types by naming them, but does not explicitly state when to use this tool versus alternatives like search_directives or search_functions. No exclusions or context about when not to use are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which cover the safety and idempotency profile. The description adds that it updates an existing record, but does not disclose potential side effects, required permissions, or what happens when the preference_key does not exist (though schema marks it as required). It adequately conveys the basic behavior but adds minimal context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence (6 words) with no unnecessary information. It is appropriately front-loaded and efficient, conveying the core purpose without any waste.
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?
Considering the tool's simplicity (5 parameters, no output schema, no nested objects), the description provides the essential action and target table. However, it lacks additional context such as authorization requirements, potential error states, or a note about the return value (if any). Given that annotations cover safety and idempotency, the description is minimally adequate but not comprehensive.
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% with all five parameters clearly described. The description does not add any additional meaning or example values beyond what the schema provides. It is a baseline score because the schema already does the heavy lifting, and the description offers no extra semantic enrichment.
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 (update) and the specific resource (existing directive preference in directive_preferences table). It effectively distinguishes itself from sibling tools like add_directive_preference (create) and load_directive_preferences (read) by indicating that it modifies an existing record.
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 implicitly indicates that this tool is for updating existing preferences, but it does not explicitly state when to use this tool versus alternatives (e.g., add_directive_preference or load_directive_preferences). There is no guidance on prerequisites or scenarios where this tool should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true. The description adds valuable context: it explains that the tool will insert if the row doesn't exist (a failsafe), and notes that this case should never happen due to SQL initialization. This goes beyond the annotations by clarifying the fallback behavior.
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 extremely concise with two short sentences. Every word is meaningful: it states the action, the resource, and the failsafe behavior. No unnecessary information is present.
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?
Given the tool has one parameter, no output schema, and annotations that declare idempotency, the description provides sufficient context. It covers the purpose, the fallback behavior, and notes that the insert case is unexpected. No additional information seems necessary for an agent to understand and use the 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 input schema covers 100% of the parameter with a clear description ('New project root path (absolute path)'). The description does not add any additional meaning beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the project root in the infrastructure table. The verb 'update' and resource 'project root' are specific. However, it does not explicitly differentiate from sibling tools like 'update_project', which might update other project fields; the name alone provides some distinction but the description could be more explicit.
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?
The description provides no guidance on when to use this tool vs alternatives. It mentions a failsafe condition but does not explain why one would choose this over other update tools like 'update_project' or 'update_project_state'. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, destructiveHint=false. The description adds that items are created with status 'pending', which is useful behavioral context. No contradictions with annotations. However, it does not disclose error behavior or limits such as maximum batch size.
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 clear, front-loaded sentences. No extraneous information. 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?
For a simple batch create tool with three parameters and no output schema, the description covers the core behavior well. It lacks details on edge cases (e.g., duplicate items, invalid parent) and usage constraints (e.g., batch size limit), but is generally sufficient.
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% with each parameter described. The description adds no further per-parameter details beyond what the schema provides. It contextualizes the operation (batch, single parent, pending status) but does not enhance parameter semantics.
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 tool batch-creates multiple work items under a single parent, with a default status of 'pending'. While it distinguishes from singular siblings like 'add_item' implicitly by mentioning batch, it does not explicitly differentiate from other similar batch tools like 'add_interactions'.
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 when adding multiple items at once, but provides no explicit guidance on when to use over alternatives (e.g., 'add_item' for single items) or when not to use (e.g., requires parent existence). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation (readOnlyHint=false) but not destructive (destructiveHint=false). The description adds 'Link' which is consistent but provides no additional behavioral details such as duplicate handling, error behavior, or constraints. It neither contradicts nor significantly enriches the annotation information.
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 exceptionally concise: two sentences that immediately state the action and a usage benefit. Every word serves a purpose, with no redundancy or irrelevant detail.
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 add operation with a single well-documented parameter, the description is largely complete. It explains the purpose and provides a query example. However, it could mention what happens on duplicates or the return value (since no output schema exists), but these omissions are minor given the tool's simplicity.
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% with a detailed description of the 'relationships' parameter, including the role enumeration. The description adds no new parameter semantics beyond what the schema already provides, 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 clearly states the verb 'Link' and specifies the objects ('tracked types' and 'functions') with a role. It also provides a concrete use case query, making its purpose unambiguous and distinct from sibling tools like delete_type_function or update_type_function_role.
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 its use for creating links between types and functions, but it lacks explicit guidance on when to use this tool versus alternatives (e.g., update_type_function_role for modifying roles) and does not address exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds behavioral detail about fallback between Git and filesystem timestamp, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every word contributes to the 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 description fails to specify the return value (e.g., boolean, timestamp). Given no output schema, this is a notable gap for a simple tool.
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 parameter file_id. The description does not add additional meaning beyond what the schema provides, so 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 uses the verb 'Check' and the resource 'file', specifying the method (Git or filesystem timestamp). It distinguishes file_has_changed from siblings like blueprint_has_changed.
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 for checking file changes but does not explicitly guide when to use this tool vs alternatives such as detect_external_changes. No when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds minimal behavioral context. It mentions 'direct keyword lookup' but does not disclose return format, case sensitivity, or behavior when no matches are found. With annotations covering safety, a 3 is appropriate.
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?
Single sentence with 11 words, entirely front-loaded with the verb and object. No superfluous language; every word is necessary for the purpose.
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 2 parameters and no output schema, the description is nearly complete. It lacks output format details (e.g., returns an array of IDs). However, given the tool's simplicity, it is sufficiently contextual for typical use.
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%—parameters 'keywords' and 'match_mode' are fully described in the schema. The description adds no additional parameter-specific meaning. Baseline is 3 due to high 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 verb 'find', the resource 'directive IDs', and the lookup mechanism 'matching one or more intent keywords'. It also distinguishes from siblings like 'find_directive_by_intent' by noting it is a 'direct keyword lookup', implying exact matching.
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 does not explicitly state when to use this tool versus alternatives like 'search_directives' or 'get_directives_with_intent_keywords'. It implies direct keyword lookup but provides no guidance on when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's addition of 'simple list' adds minimal behavioral context. The description is consistent with annotations but does not go beyond.
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, front-loaded sentence with no wasted words. It efficiently conveys the core functionality.
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 list retrieval tool with no parameters and annotations covering safety, the description is nearly complete. However, it could have specified the return format (e.g., array of strings) to compensate for the lack of output schema.
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 no parameters, and the schema coverage is 100%. The description adds no parameter semantics but the absence of parameters makes this a non-issue. Baseline for 0 params is 4.
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 returns 'all unique intent keywords' for 'searching', and distinguishes it as a 'simple list'. This verb+resource description distinguishes it from similar siblings like 'get_directive_keywords' which may filter by directive.
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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or context in which 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so description doesn't need to repeat. However, it adds no behavioral context beyond what's in annotations, such as error cases (e.g., detached HEAD).
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?
Single sentence with no wasted words. Perfectly concise for a trivial tool.
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-only tool with no parameters, the description is complete enough. It doesn't explain return format or edge cases, but these are minor omissions for such a straightforward 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?
No parameters; schema coverage is 100%. Baseline score of 4 is appropriate as per guidelines.
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 uses specific verb 'Get' and resource 'current Git branch name'. It clearly distinguishes from sibling tools like 'get_current_commit_hash', 'get_git_status', and 'list_active_branches'.
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 on when to use this tool versus alternatives (e.g., 'list_active_branches' for all branches). Agent must infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint, idempotentHint) but does not add extra behavioral context beyond what annotations already specify.
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 concise sentence with no unnecessary words.
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, no-parameter tool, the description covers the basic purpose. However, it omits details about the return format (e.g., full vs short hash), which would help.
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?
There are no parameters, and the schema coverage is 100%. The description implies no arguments are needed, which 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 'Get current Git HEAD commit hash', which is a specific verb and resource. It distinguishes from sibling tools like get_git_status that serve a different purpose.
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 provided on when to use this tool versus alternatives like get_git_status. There is no mention of when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds semantic label 'intent' but no behavioral depth beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words, front-loaded with action and object, no waste.
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 tool with one parameter and annotations covering safety/idempotency, the description is sufficient but could mention return format.
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% with parameter description 'Directive ID'. Description adds no further meaning to the parameter.
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 says 'Get all intent keywords for a specific directive', which is specific, uses a verb, and distinguishes from siblings like get_all_directive_keywords and find_directive_by_intent.
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?
Implies use when needing keywords for one directive, but provides no explicit guidance on when to avoid or alternatives like get_all_directive_keywords.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, indicating the tool is safe and idempotent. The description adds no behavioral context beyond the filtering condition. It does not describe the return format, pagination, or any side effects, but no contradictions exist.
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 conveys the essential information without any fluff. It is front-loaded with the action and resource, making it easy 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 get tool with no parameters and no output schema, the description is fairly complete. It specifies the filtering condition. However, it could be more complete by hinting at the return type (e.g., 'returns a list of helper names'). Still, it adequately serves its purpose.
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 input schema has zero parameters, and schema_description_coverage is 100% (vacuously). The description does not need to explain parameters, so the baseline of 4 is appropriate. No additional parameter information is necessary.
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 purpose: retrieving all sub-helpers (where is_sub_helper=true). It uses a specific verb ('Get') and resource ('sub-helpers'), and the condition in parentheses distinguishes it from sibling tools like get_helpers_are_tool and get_helpers_not_tool_not_sub.
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 the tool (when needing sub-helpers) but provides no explicit guidance on when not to use it or mentions alternatives among siblings. An agent would benefit from knowing that get_helpers_are_tool or get_helpers_not_tool_not_sub exist for different filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, covering safety and idempotency. Description adds no behavioral details beyond purpose, which is acceptable given annotation coverage.
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?
Single sentence, concise, no unnecessary words, front-loaded with key information.
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?
No output schema, and description does not clarify what 'infrastructure' means or the structure of returned data. For a read operation, more context on return format would be helpful.
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% with parameter description including examples. Description adds no extra meaning beyond the schema, so 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?
Clearly states verb 'Get' and resource 'infrastructure' with specific filtering by type. Distinguishes from sibling 'get_all_infrastructure' which returns all without filter.
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?
Implicitly tells when to use: when you need infrastructure of a specific type. Sibling tool 'get_all_infrastructure' provides alternative, but no explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotent and read-only. Description adds return field details (path, purpose, external_dependencies), providing extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, single sentence. Front-loaded with action and result, no wasted words.
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?
No output schema exists, so description compensates by listing return fields. Tool is simple and well-defined. Could mention case sensitivity or behavior when module not found, but not critical.
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?
Input schema has 100% coverage for the sole parameter 'name' with a clear description. The description does not add any 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?
Clearly states it gets a module by name and returns specific fields (path, purpose, external_dependencies). Distinguishes from siblings like get_module_by_path by lookup key.
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 on when to use this tool over alternatives (e.g., get_module_by_path, get_all_modules). Does not provide contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds internal mechanism ('junction table') but no extra behavioral traits.
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 efficient sentence with no superfluous words.
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?
Sufficient for a simple lookup with one parameter and annotations covering behavior; could mention return type but not required per rules.
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 100% already documents file_id; description adds no additional meaning.
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?
Clearly states it finds which module a file belongs to via reverse lookup, distinguishing it from forward lookup siblings like 'get_module_files'.
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?
Implies usage through 'reverse lookup' but no explicit when-to-use or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's addition of the join logic adds minimal behavioral context. No contradictions, but no significant disclosure beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero fluff. The first sentence states the primary function, the second adds a necessary detail about the join. No wasted words.
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 tool with one parameter and no output schema, the description adequately explains the tool's function and join mechanism. However, it could briefly describe the return data format to be fully 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?
The description provides no additional parameter information beyond what the schema already describes (module_id integer). Schema coverage is 100%, so 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 clearly states the action 'Get' and the resource 'all functions in module files', effectively distinguishing it from siblings like 'get_functions_by_file' by specifying the join through module_files. 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 when to use (when needing functions for a module) but provides no explicit guidance on alternatives or when not to use. Given the many sibling tools for retrieving functions, some exclusion criteria would improve score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat that. The phrase 'complete schema' implies comprehensive output. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It 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?
With no output schema and many similar sibling tools, the description could be more specific about what 'complete schema' includes (e.g., JSON schema, table definitions). It is adequate but leaves ambiguity.
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?
There are zero parameters, so the description has no need to add meaning beyond the schema. It is sufficient.
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 verb 'get' and the resource 'complete schema for user settings database'. However, with sibling tools like 'get_settings_fields' and 'get_settings_tables', it's not fully differentiated what 'schema' specifically includes (e.g., column types, constraints). Still, it provides a clear purpose.
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 on when to use this tool versus other settings-related tools (e.g., get_settings_fields, get_settings_tables). The description does not mention context, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds 'Get flow IDs' which is consistent but does not disclose return format, error handling, or behavior for missing sidequests. With strong annotations, the description provides minimal additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys all necessary information. It is concise and front-loaded, with no redundant words. Every part is justified.
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 tool has one parameter, full schema coverage, no output schema, and annotations covering safety, the description is largely complete. It states the purpose and scope. However, it does not mention the return format (e.g., array of strings), which could be helpful. Still, it is sufficient for a simple read 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?
The input schema has one parameter (sidequest_id, integer) with description 'Sidequest ID'. The tool description does not add any meaning beyond the schema, which is already descriptive. With 100% schema coverage, baseline 3 is appropriate; no extra semantics provided.
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 'Get flow IDs for a sidequest' clearly states the verb (get), resource (flow IDs), and scope (for a sidequest). It effectively distinguishes from sibling tools like get_all_flows (all flows) or get_flows_for_file (by file).
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?
No explicit when-to-use or alternative guidance is provided. The purpose is clear, but the tool does not specify when to use this over similar sibling tools like get_flows_for_theme or get_flows_from_directive. Context implies use for sidequest flows, but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds 'fairly frequent' as a behavioral note about usage frequency, but does not disclose other traits like error handling or permissions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded 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?
Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is nearly complete. It could mention what happens if the key is not found or the return format, but the current level is sufficient.
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% (the parameter 'setting_key' has a description). The tool description adds no additional meaning beyond the schema, so baseline 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 specifies the verb 'Get' and resource 'project-wide user setting by key', clearly distinguishing it from sibling tools like 'get_user_settings' (plural) or 'get_settings_fields'.
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 for retrieving a single setting by key but does not explicitly state when to use this tool versus alternatives (e.g., when to use 'get_user_settings' instead). No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that results include FP references, utilities, and cross-cutting concerns, providing extra behavioral context without contradicting 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?
Two sentences, zero waste. First sentence front-loads purpose and scope, second lists included items. Highly 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?
Simple tool with one optional param and no output schema. Description adequately covers what is retrieved and its special status (wildcard). Lacks explicit output format, but given the tool's simplicity, it 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?
With 100% schema description coverage for the single optional parameter, the description adds no additional semantic meaning beyond what the schema already provides. Baseline score 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 retrieves 'all directive flows from wildcard '*' source', specifying scope and contents (FP references, utilities, cross-cutting concerns). This distinguishes it from siblings like get_all_flows or get_directive_flows.
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 for universal flows (wildcard) but does not explicitly state when to use or avoid this tool versus alternatives. No direct comparison or exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds key behavioral info beyond annotations: it's a batch operation requiring definition_json and description for every type. Annotations are minimal (no destructive hint, not read-only), so description carries burden. Could mention idempotency or side effects but overall helps.
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-loaded with verb 'Batch-reserve', no fluff. Every sentence earns its place.
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?
No output schema exists, but description does not explain return value (e.g., reserved IDs). Also lacks mention of error cases or prerequisites. Incomplete for a batch 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% with detailed parameter description. Description reinforces required fields (definition_json, description) but does not add new meaning beyond schema. Baseline 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?
Clearly states the tool batch-reserves type IDs before writing multiple type definitions, using specific verb and resource. Distinguishes from siblings like reserve_type (singular) and other reserve tools.
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?
Implies usage context (before writing multiple type definitions) but does not explicitly state when to use this versus alternatives like reserve_type or finalize_types, nor provide when-not or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds no extra behavioral context beyond the fact that it updates metadata. It does not disclose side effects, authorization requirements, or any nuances beyond what annotations provide.
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 concise sentence that is front-loaded with the essential purpose. No redundant information is present, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the minimal description, the tool is straightforward (update metadata with optional fields) and the schema covers parameter semantics. The lack of output schema is acceptable. Slightly docked for not explicitly stating the 'NULL=don't update' pattern, though it is in the schema.
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 itself documents all parameters with their meanings (including NULL=don't update). The description does not add additional 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 'Update interaction metadata' clearly states the action (update) and resource (interaction metadata). The name 'update_interaction' is self-explanatory and distinguishes from siblings like add_interaction and delete_interaction.
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?
No explicit guidance on when to use this tool versus alternatives like add_interaction or get_interactions_by_function. The context implies it is for updating existing interactions, but no when-not or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description aligns by describing a delete operation. It adds behavioral context (abandoned entries, escape hatch) beyond annotations, without contradictions. No annotation contradiction found.
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?
Single sentence with efficient wording. Front-loaded with verb and resource, no wasted words.
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?
Adequate for a simple delete tool with rich schema, but could provide more context about what 'reserved entries' are and the safety implications of a destructive action. Missing explanation of note parameter logging.
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% with clear descriptions for all 6 parameters. The description adds no parameter-specific information, so 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 verb 'Delete' and the resource 'abandoned reserved entries', with additional context 'escape hatch for cancelled reserve operations'. This effectively distinguishes it from sibling delete tools like delete_file or delete_function.
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 for cancelled or abandoned reservations but does not explicitly state when to avoid this tool or mention alternatives like delete_file for actual resources. The context 'escape hatch' provides some guidance, but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, repeatable behavior. The description adds that it retrieves conflict data, which is useful but not extensive. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the key action. Every word is meaningful with no redundancy.
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 description does not detail the return format of conflict data, which could be important for an AI agent. It is adequate for the context but lacks completeness regarding output.
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 parameter 'source_branch' is self-explanatory. The description does not add additional meaning or constraints 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 it is a 'dry-run merge analysis' that retrieves potential conflict data. This distinguishes it from related siblings like 'execute_merge' and aligns with the title 'Detect Conflicts Before Merge'.
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 usage before executing a merge ('dry-run') but does not explicitly state when-not-to-use or provide alternatives. It is clear enough for the intended purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not destructive. The description adds behavioral context by stating it triggers 'interaction and type-function relationship checks,' but does not disclose what happens on failure, reversibility, or permissions needed. This adds some value but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and add a key side effect. No wasted words or redundancy.
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's complexity (7 parameters, nested objects, no output schema), the description is minimal. It does not guide how to fill optional parameters like purpose or returns, nor explain the return behavior. Adequate but not fully comprehensive.
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%, so the schema already documents all 7 parameters. The description does not add meaning beyond the schema, thus 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 action ('mark a reserved function as tracked') and the resource ('function'), and mentions a side effect (triggers checks). It distinguishes from siblings like finalize_file or finalize_type by specifying the function context.
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 provides context ('after writing it') implying when to use, but does not explicitly state when not to use or contrast with alternatives among the many sibling finalize tools. The guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the agent knows it's safe and idempotent. The description adds that it returns usage counts, which is helpful context beyond annotations. However, it does not disclose potential performance implications or output size, which could be relevant for large datasets.
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, front-loaded sentence that conveys the core function without extraneous words. It efficiently communicates the purpose and key deliverable (unique keywords with counts).
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?
While the description adequately states the purpose for a simple read tool, it lacks details about the output format (e.g., an array of objects with keyword and count fields). Since there is no output schema, the description bears the burden of explaining the return structure, which it does not do. This could leave the agent uncertain about the data shape.
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 no parameters (0), and schema coverage is 100%. The description adds no parameter details because none exist, but it does add meaning by specifying the counts aspect. Baseline for 0 params with complete schema is 4, and the description meets that.
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 retrieves 'all unique intent keywords with usage counts for analytics,' specifying both the resource (intent keywords) and the additional value (counts). It distinguishes itself from siblings like 'get_all_directive_keywords' which likely returns keywords without counts, and implies a distinct use case for analytics.
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 for analytics when counts are needed, but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. Given the sibling set, it could give more guidance about when not to use it (e.g., if only keywords are needed, use get_all_directive_keywords).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds 'with metadata' but does not elaborate further. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundant words. Every part is informative.
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?
Given no parameters, annotations covering safety, and a simple list operation, the description is sufficiently complete. No output schema is needed for this straightforward retrieval.
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?
Input schema has 0 parameters, so baseline is 4. Description does not need to add parameter details.
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 clearly states the action ('Get list') and resource ('all available databases') and adds specificity with 'with metadata'. It distinguishes from sibling tools like get_core_tables or get_project which focus on specific data types.
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 explicit guidance on when to use this tool versus alternatives (e.g., get_core_tables, get_project). Given the large number of sibling tools, explicit usage context would help the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnly and idempotent hints, covering safety. The description only mentions filtering, adding no extra behavioral context beyond what annotations already convey.
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, front-loaded sentence that conveys essential information without wasted words.
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 description omits output format, pagination, and the fact that all parameters are optional, but given high schema coverage and readOnly annotation, it is minimally adequate.
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?
With 100% schema description coverage, the description lists filter fields but adds little beyond the schema's detailed parameter descriptions. 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 it queries notes with structured filters (type, reference, source, severity, directive) and distinguishes from keyword search, making its purpose specific and differentiating it from siblings like search_notes.
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 indicates targeted retrieval without keyword search, implying when to use; however, it does not explicitly list alternatives or when not to use it, though the context of siblings provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds no behavioral details (e.g., return format, performance considerations). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded with purpose. Appropriate length for a parameterless 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?
Given no parameters and annotations covering safety, description could be more informative about output (e.g., what the schema includes). Lacks details on return structure, making it less complete for an agent.
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?
No parameters exist, so baseline is 4. Description does not need to add param info; schema coverage is 100%.
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 clearly states 'Get complete schema for project database' with a specific verb and resource. It distinguishes from sibling tools like get_core_schema and get_settings_schema by specifying 'project'.
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?
No explicit guidance on when to use this tool versus alternatives like get_core_schema or get_settings_schema. Usage is implied (to retrieve project schema) but no exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds context about identifying gaps but does not elaborate on behavioral details like return format or file scope. Adds moderate value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with action and purpose. Efficiently conveys the tool's function and value.
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?
Lacks specification of output format (e.g., list, file paths) or scope (e.g., all files, only domain logic?). Adequate for a simple tool with no parameters and annotated safety, but could be more complete regarding result structure.
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?
No parameters in input schema, and schema description coverage is 100%. Description does not need to add parameter info, baseline score 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?
Clearly states 'find files not assigned to any module', uses specific verb and resource, and explains usefulness for tracking gaps. Distinguishes from sibling tools like 'get_module_files' or 'get_module_for_file'.
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?
Explicitly mentions when it's useful (identifying tracking gaps for domain logic files). Does not state when not to use or provide alternative tools, but the purpose is clear enough to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description says 'Creates the database,' implying mutation. It does not specify idempotency or side effects on existing databases, which is a gap. However, no contradiction with annotations is apparent.
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 with no wasted words. Front-loaded with purpose and usage instruction.
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 init tool with no parameters or output schema, the description covers essential purpose and usage. Missing details like return behavior or safety for repeated calls, but still adequate.
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?
No parameters exist, so schema coverage is 100%. The description appropriately does not add parameter information. Baseline for 0 parameters is 4.
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 tool initializes user_directives.db for Case 2 projects, with a specific verb and resource. It is distinct from many siblings but does not explicitly differentiate from other initialization tools like create_state_database.
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?
Provides explicit context: 'Call when project transitions to Case 2.' This tells the agent when to use it, but does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds the source table but no additional behavioral traits beyond what annotations provide.
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?
Single sentence with no unnecessary words. Efficient and front-loaded.
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 simple read-only list tool with no parameters and no output schema, the description is complete, specifying the source table.
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?
No parameters exist, so schema coverage is 100%. Baseline score of 4 is appropriate as description adds no parameter details but none are 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?
Description clearly states it lists all AIMFP work branches from a specific table, using a specific verb and resource. Differentiates from siblings like get_current_branch and create_user_branch.
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 on when to use this tool versus other branch-related tools. Lack of context on when it is appropriate compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds context about batch update and primary use, but does not reveal additional behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states general function, second gives primary use case. Very efficient.
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?
Missing return value information (e.g., success status, count of updated items). With no output schema and nested objects, description could be more 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 coverage 100% with descriptions for ids and data. Description adds 'the same field values' for data, but not significant extra meaning beyond 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?
Clearly states batch-update of multiple items with same field values, and provides primary use case of marking items completed when parent completes. Distinct from singular update_item.
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?
Gives a specific primary use case ('marking multiple items completed at once when parent completes'), but lacks explicit guidance on when not to use or alternatives like update_item for different values per item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (modification), destructiveHint=false, and idempotentHint=false. The description adds that it 'Skips existing links silently', which clarifies idempotency behavior. However, there is no additional context on permissions, rollback, or partial failures beyond what annotations imply.
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, directly stating purpose and key behavior. No fluff, front-loaded with the verb and resource.
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 batch operation with one parameter, the description covers purpose, efficiency, and behavior on duplicates. It lacks details on error handling or return values, but given the lack of output schema and simplicity, it is largely 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 coverage is 100%, so the schema already describes the 'links' parameter as an array of tuples. The description does not add any new detail about parameters. 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 'Batch-assign multiple files to flows', specifying the action (batch-assign), resource (files to flows), and scope. It also distinguishes from the sibling 'add_file_to_flow' by highlighting efficiency.
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 mentions efficiency over multiple add_file_to_flow calls, guiding when to use the batch version. It also notes that existing links are skipped silently, implying idempotent behavior. However, it does not provide explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only (write operation) and non-destructive. The description adds that the file must be finalized, but does not disclose whether re-assignment replaces existing flows, or what happens if the file or flow does not exist. With annotations present, the description's additional behavioral info is minimal.
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, using two sentences with no redundant information. The key action and context are front-loaded, making it easy for an agent to quickly understand the tool's purpose.
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 parameters and no output schema, the description adequately covers purpose and one usage context. It lacks details on error conditions (e.g., file not finalized, invalid flow ID) but is sufficient for typical use cases given the sibling tools and schema descriptions.
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?
Input schema coverage is 100% with both parameters described. The description does not add new semantic information beyond what the schema already provides, 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 purpose: assign a finalized file to an architectural flow. It distinguishes from sibling tools like add_file_to_module by specifying the target resource as a flow, and provides context about the requirement for connectivity.
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 indicates when to use this tool by noting that every finalized file needs at least one flow assignment, implying this is for maintaining architectural connectivity. However, it does not explicitly state when not to use it or mention alternatives like add_file_flows (plural).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read, non-destructive mutation. The description adds the batch nature but no additional behavioral context about side effects, permissions, or constraints. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no redundant 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?
Given the simple structure (one parameter fully described in schema, no output schema) and the presence of annotations, the description is adequately complete, though it could mention return behavior.
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 description does not add further meaning beyond the schema's detailed description of the 'interactions' parameter.
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 records function dependencies in batch by ID, and distinguishes it from the sibling 'add_interaction' tool by noting efficiency for multiple dependencies.
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 explicitly recommends use for batch recording and positions it as more efficient than calling add_interaction multiple times, providing clear guidance for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=false, readOnlyHint=false), the description adds the side effect that the parent task is paused until all subtasks complete, which is valuable behavioral context not captured in structured fields.
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 concise sentence that front-loads the core purpose and key behavior, with zero wasted words.
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?
While the description effectively conveys purpose and a key behavioral trait, it omits details such as what the tool returns (no output schema) or any prerequisite conditions. This is adequate but leaves minor gaps.
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 description does not elaborate on parameters, providing no additional meaning beyond what the schema already documents. 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 clearly states the tool creates a sub-unit under a parent task with the unique behavior of pausing the parent until subtasks complete. This distinguishes it from sibling tools like 'add_task' which manage top-level tasks.
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 when subtasks are needed under a parent, but does not explicitly state when not to use or provide alternatives among siblings like 'add_sidequest' or 'add_item'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds the behavioral nuance that tasks are created singly over time, which is useful but still limited in depth.
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: first states purpose, second adds important usage context. 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?
For a simple creation tool with good schema and annotations, the description is reasonably complete. Could have mentioned return value but output schema is absent.
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% so baseline is 3. The description mentions 'flow associations' but does not add new semantic detail beyond what the schema already provides for each parameter.
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 ('create'), the resource ('task'), and the context ('under a milestone with flow associations'), distinguishing it from sibling tools like add_milestone or add_flow.
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 by noting tasks are created one at a time as work progresses, but does not explicitly mention when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readonly=false (write operation) and destructive=false. Description adds context that it targets user_preferences.db and requires tracking enabled, which is useful behavioral info beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Essential information (verb, target, condition) is front-loaded and 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 well-documented schema and no output schema, the description provides purpose and condition. Slight gap: could mention behavior if tracking is disabled, but overall adequate.
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 has 100% coverage with descriptions for all 8 parameters. Description does not add additional meaning beyond the schema, so 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?
Clear verb 'Add' and resource 'tracking note to user_preferences.db' with condition 'only when tracking enabled'. Distinguishes from sibling 'add_note' by specifying tracking context.
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?
States condition 'only when tracking enabled', providing clear context for use. Does not explicitly mention when not to use or alternatives like 'add_note' for general notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true). The description adds detail on deletion modes (by ID, text, or all) but does not elaborate on consequences like potential breaking of functions or irreversible changes. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and directly states the purpose and deletion methods. No unnecessary words; efficient for agent parsing.
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 straightforward deletion tool with three parameters, the description covers all deletion modes and the required helper. It lacks mention of error handling or success confirmation, but the simplicity and annotation support make it reasonably complete.
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?
With 100% schema coverage, the description adds value by clarifying that omitting both optional fields results in deleting all return statements for the helper. This semantic is not apparent from the schema alone, where optional fields could be interpreted as just not filtering. The description resolves ambiguity.
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 ('delete') and resource ('custom return statement(s) for a helper function'), and outlines three deletion methods. This clearly differentiates from sibling tools that delete other entities.
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?
While the description clarifies the deletion targets, it does not provide explicit guidance on when to use this tool versus alternative approaches (e.g., updating the statement to a new value). No exclusion criteria or context for preference is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide non-read-only and non-destructive hints. The description adds behavioral details: triggers flow assignment and function/type tracking checks. This goes beyond the annotations and gives the agent insight into side effects, though it could mention reversibility or permissions.
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, front-loading the primary action and then listing side effects. Every sentence serves a purpose.
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 5 parameters, no output schema, and annotations describing safety, the description covers the main function and side effects. It lacks details on error conditions or prerequisites, but is adequate for a mutation tool.
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%, so each parameter has a description. The tool description does not add any additional meaning or context for the parameters beyond what is in the schema, meeting the baseline expectation.
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 'mark' (equivalently 'finalize') the resource 'a reserved file' and specifies the context 'after writing it to disk'. It distinguishes from siblings like finalize_files (plural) and finalize_function by focusing on a singular file resource.
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 after writing a reserved file to disk, but does not explicitly state when not to use it or compare to alternatives like reserve_file or finalize_files. This provides some context but lacks clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's burden is reduced. It adds that the tool returns the 'most relevant directive(s)', implying ranking, but does not detail the matching mechanism or output format.
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 front-load the purpose and usage, with no unnecessary words. Every sentence 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 tool's simplicity and annotation richness, the description is mostly complete. However, it lacks explanation of return structure (e.g., list of directives with confidence), which could be helpful.
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 baseline is 3. The description does not add significant meaning beyond the schema; it only reiterates the tool's purpose without elaborating on parameters like threshold's role in relevance.
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 matches a natural-language user request to relevant directives, using a specific verb and resource. It distinguishes from sibling tools like 'find_directives_by_intent_keyword' by focusing on intent matching rather than keyword matching.
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?
Explicitly states when to use: when the user describes what they want and you need to find which directive handles it. Does not mention explicit exclusions or alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of 'ordered' roadmap adds minimal behavioral context beyond what annotations provide. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and immediately clarify the hierarchical structure. No extraneous 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?
Given no output schema, the description explains the nested structure (paths > milestones > tasks). It is reasonably complete for a simple retrieval tool, though a bit more detail on the return format would strengthen it.
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 input schema has 0 parameters with 100% coverage. With no parameters, the description adds no additional semantic value, but baseline is 4.
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), resource (project's ordered completion roadmap), and structure (paths contain milestones, milestones contain tasks). It distinguishes from sibling tools like get_milestones_by_path or get_tasks_by_milestone.
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?
No explicit when-to-use or when-not-to-use guidance is provided. While the name implies getting all completion paths, there are no mentions of alternatives or situations where a different tool might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read. The description adds 'complete schema' but does not disclose other behavioral aspects like output size or format, offering little beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence of 9 words, efficiently stating purpose with no redundancy. Fully front-loaded.
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 parameterless, read-only tool with clear annotations, the description is reasonably complete. It states it returns the full schema, which is sufficient. Could mention output format or caution about large results, but not strictly needed.
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?
There are no parameters, so the schema coverage is 100%. The description does not need to add parameter meanings. Baseline of 4 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 uses the specific verb 'Get' and identifies the resource as 'complete schema for core database (all tables and fields)'. This clearly distinguishes it from sibling tools like get_core_fields (only fields) and get_core_tables (only tables).
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 you need the complete schema) but does not explicitly state when not to use it or mention alternatives. With many sibling get_* tools, explicit guidance would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is known. The description adds no further behavioral context beyond being a general query, which is adequate but not enhanced.
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?
Extremely concise: two sentences, front-loaded with key information, no unnecessary words.
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 annotations and complete schema, the description covers the essential context. It could mention return format, but the tool's simplicity and lack of output schema reduce the need.
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%, so each parameter already has a description. The main description does not add parameter details, but that is acceptable when schema is complete.
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 it is a general-purpose query for directive flows, specifying the resource and action. It distinguishes itself from specialized navigation helpers, 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?
It mentions complementing specialized navigation helpers, providing context on when to use this tool over alternatives. However, it does not give explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds behavioral context about return values (metadata, path, ID) and workflow placement, consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with action and context. Every sentence 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 no output schema, description adequately explains return content (metadata, path, ID). Input is simple, read-only operation; missing details like error cases but acceptable for this tool.
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 has 100% coverage with description and example for the only parameter ('file_name'). Description adds no extra meaning beyond what the schema provides, so 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?
Clear verb ('look up') and resource ('tracked file by name'). Description distinguishes by specifying workflow ('use BEFORE reading source files'), though sibling differentiation is not explicit.
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?
Explicit 'use BEFORE reading source files' provides clear when-to-use. States return value purpose for follow-up, but does not mention when not to use or alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, so the description does not need to restate read-only nature. The description adds no behavioral details beyond the scope (all flows leading to directive), which is sufficient given the existing 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?
Two sentences with zero wasted words. Front-loaded with the key action and resource, followed by a usage hint. Highly 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 read-only query tool with one parameter and no output schema, the description is nearly complete. It could mention the return format, but is adequate as is.
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% with a clear description 'Target directive name'. The description adds only the parenthetical hint, which does not significantly enhance parameter meaning. 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 verb 'Get' and the resource 'directive flows leading to a directive', and distinguishes from sibling 'get_flows_from_directive' by specifying direction ('leading to'). The parenthetical '(what leads here?)' further clarifies intent.
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 states it is 'useful for understanding directive prerequisites', which implies when to use it. However, it does not explicitly exclude alternatives like 'get_flows_from_directive' or 'get_directive_flows', though the tool name and sibling list provide differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe and idempotent behavior. The description adds value by specifying that an empty id_array returns all records, which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action 'Get records...' and contains no unnecessary words. It is appropriately sized and 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?
Given the simplicity of the tool (two parameters, high schema coverage, annotations present, no output schema), the description covers the core behavior. It could mention the return format or that it only works on core tables, but it is largely complete for an agent to understand usage.
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 parameters already well-described in the input schema (table as 'Table name', id_array with empty array behavior). The tool description does not add any additional parameter-level information 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 tool fetches records by ID(s) or all records if the array is empty. The verb 'Get' and resource 'records from core' are specific. Among siblings like 'get_from_core_where' and 'get_from_project', this tool is distinguished by its retrieval method (by IDs or all).
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 for fetching records by IDs or all, but it does not explicitly mention when to use this tool versus alternatives like 'get_from_core_where' for filtered queries. No exclusions or alternative tool names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description does not contradict these and adds context about directive workflows, but it does not disclose behaviors like error handling, pagination, or performance beyond what annotations cover.
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 with two sentences, front-loading the primary action. Every word adds value, and there is no wasted or redundant text.
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 lack of output schema and moderate complexity, the description provides the core purpose and usage context. It does not detail the return structure, but the tool's simplicity and good annotations make it fairly complete for an AI agent's needs.
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 has full description coverage (100%) for both parameters. The description does not add any additional meaning or context for the parameters beyond what is in 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 it retrieves the list of MCP tools for a directive workflow. It distinguishes from sibling tools like 'get_helper_by_name' and 'get_helpers_by_database' by specifying the context of directive steps. The verb 'Get' and resource 'list of MCP tools' are specific.
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 guides when to use the tool: 'Use to discover which tools to call when executing a directive's steps.' It implies the context but does not explicitly exclude other scenarios or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. The description adds no behavioral context beyond 'non-completed', not adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. Front-loaded with 'Get all non-completed sidequests'.
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 parameters and no output schema, the description is sufficient for a simple retrieval tool. Could mention return format, but not essential.
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?
No parameters exist, so schema coverage is 100%. Baseline 4 for no parameters is appropriate; description correctly indicates the tool takes no inputs.
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' and the specific resource 'non-completed sidequests'. This distinguishes it from sibling tools like 'get_sidequests_comprehensive' which likely returns all sidequests.
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 for retrieving incomplete sidequests but does not explicitly state when to use this tool versus alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark as readOnly and idempotent. Description adds that the tool retrieves files via the module_files junction table, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that fully describes the tool's purpose. No unnecessary words.
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 1 parameter and no output schema, the description is sufficiently complete. It clearly explains what the tool returns and how.
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?
Only one parameter (module_id) with 100% schema coverage. Description adds no extra meaning beyond the schema's 'Module ID'.
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 clearly states the action (get), resource (files assigned to a module), and mechanism (via module_files junction table). Distinct from sibling tools like 'get_file_by_name' or 'get_module_functions'.
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?
No explicit guidance on when to use this tool vs alternatives. Usage is implied by the name and description, but lacks comparisons to similar tools like 'get_module_functions' or 'get_task_files'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds context about the junction table join, aiding understanding of data retrieval behavior.
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-loaded with main action, no superfluous content.
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?
Adequately explains the tool's operation for a low-complexity tool; could optionally mention expected output structure, but description covers the core join logic.
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 provides 100% coverage for the single parameter (module_id with description). Description adds no extra meaning beyond what the schema offers.
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?
Clearly states 'Get all types in module files', providing a specific verb and resource. Explains the underlying join through module_files, distinguishing it from generic get tools.
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?
Implies usage when needing types for a module, but no explicit when-to-use or alternatives are mentioned among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the tool's non-destructive, idempotent behavior. The description adds no additional behavioral context beyond what annotations provide, such as return format or edge cases (e.g., no incomplete paths). With annotations present, the description provides minimal added value.
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, clear sentence with no wasted words. It front-loads the key action and criterion, making it easy for an agent to quickly understand what the tool does. 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?
The tool is simple (0 parameters, no output schema). The description adequately explains the purpose but does not specify the return format (e.g., whether it returns a path object or only the order_index). Given the simplicity, the description is nearly complete, though slightly more detail about the return value would be helpful.
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 no parameters, and schema description coverage is 100% (trivially). Since there are no parameters, the description does not need to add parameter semantics beyond what the schema provides. The baseline for 0 parameters is 4, and the description meets this without adding unnecessary information.
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 'Get lowest order_index with status != completed' directly states the action (get) and the specific criterion (lowest order_index that is not completed). This clearly distinguishes it from siblings like get_all_completion_paths or get_completion_paths_by_status, which have different filtering or scoping.
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 for retrieving the next incomplete completion path, but it does not explicitly state when to use this tool versus alternatives such as get_incomplete_completion_paths or get_completion_paths_by_status. No when-not or alternative guidance is provided, which is a minor gap given the many sibling tools for completion paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the context of reading from 'infrastructure table', but no further behavioral details (e.g., potential empty result, performance characteristics). This adds some value beyond annotations but not significantly.
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?
Single sentence, clear and to the point. No unnecessary words, effectively conveys the tool's purpose.
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 parameters, annotations providing safety profile, and no output schema, the description is mostly complete. It could optionally mention the return type (e.g., a string), but the current level is adequate for a simple getter.
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 no parameters, so baseline is 4. No parameter documentation is needed, and the description does not add any parameter-specific information, which 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?
Description clearly states 'Get project root directory from infrastructure table', specifying the action, resource, and data source. This distinguishes it from sibling tools like 'update_project_root' (write) and 'get_source_directory' (different field).
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?
Description implies usage when the project root is needed, but provides no explicit guidance on when to use this tool versus alternatives such as 'get_source_directory' or 'get_project'. No exclusionary criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true, so safety and idempotence are covered. Description adds that data comes from infrastructure table, but no further behavioral traits (e.g., return format, failure 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?
Single sentence of 7 words, no redundancy, all essential information present.
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 parameterless read tool with annotations, description covers purpose and data source. However, it does not specify return type (e.g., string path) which would improve completeness.
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?
No parameters exist and schema coverage is 100%, so description does not need to add parameter information. Baseline for 0 parameters is 4.
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 clearly states verb 'Get' and resource 'project source directory' from 'infrastructure table', distinguishing it from siblings like update_source_directory and get_project_root.
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?
No explicit guidance on when to use this tool versus alternatives like get_project_root or get_all_infrastructure. Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds the optional filtering behavior, which is not annotated. No contradictions. This is appropriate 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?
The description is a single concise sentence that front-loads the essential information. No wasted words or unnecessary detail.
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 tool with a clear schema and no output schema, the description and schema together provide adequate completeness. Could mention return format but not necessary.
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%, so both parameters are described in the schema. The description adds no additional meaning beyond the schema, meeting the baseline for high 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 action ('Get') and the resource ('subtasks for task'), with a specific optional filter by status. It distinguishes from sibling tools like 'get_incomplete_subtasks_by_task' and 'get_subtasks_comprehensive'.
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 for retrieving subtasks of a specific task with optional filtering, but does not explicitly contrast alternatives or provide when-not-to-use guidance. Given the many sibling tools, more guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe, idempotent read operation. The description adds value by explaining the auto-provisioning behavior and the fact that it returns reference documents, but does not disclose additional behavioral traits beyond what annotations imply.
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 extremely concise: two sentences that pack the core purpose and behavioral details without any fluff or repetition. Every sentence serves a purpose.
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 tool has one parameter, no output schema, and comprehensive annotations, the description is largely complete. It explains all variants and when they are auto-provided. It could optionally detail the return format (e.g., 'list of document strings') but the absence is minor for a simple retrieval tool.
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 provides 100% coverage for the single parameter 'variant', including a description and default value. The tool description mentions variants but does not add new semantic information or format details beyond what is already in the schema's parameter description. 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 returns supportive context reference documents by variant, and enumerates the available variants (core, coding, case2, init). This specific verb+resource combination distinguishes it from numerous sibling get_* tools.
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 explains when variants are auto-provided (e.g., core and coding via aimfp_run with is_new_session=true, case2 when active, init via aimfp_init()) and mentions it is callable on demand to reload stale context. It gives clear context for usage but does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by noting it 'uses cached project root internally' and that retrieval is optional for some components. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. No extraneous words; every sentence provides essential 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?
Comprehensive for a tool with no output schema: lists all retrieved data types. Could benefit from brief mention of return structure, but given sibling complexity and annotations, this is adequate.
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 description mentions auto-detection of task_type and optional includes. However, it does not add significant meaning beyond the schema descriptions themselves.
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 it retrieves 'complete context for resuming work on a specific task/subtask/sidequest' and lists all components returned (item, associated items, flows, files, functions, optionally interactions and notes). This distinguishes it from more specific sibling tools.
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 when full context is needed but provides no explicit guidance on when to use alternatives (e.g., get_task_files, get_task_flows). It mentions it's a 'single call' but does not contrast with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description does not need to reiterate safety. It adds value by specifying the return content (field names, types, required), but no additional behavioral traits are disclosed.
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-loading the purpose and immediately listing return information. Every sentence is necessary and efficiently conveys the tool's function.
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-only tool with one parameter and no output schema, the description provides sufficient context: what it does, what it returns, and and when to use it. It could mention that it applies to user_custom tables, but the name already implies that.
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 single parameter 'table' is fully described in the input schema (100% coverage). The description does not add new semantic details beyond the schema, meeting the baseline expectation.
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 gets available fields for a table, specifying the purpose is to use with generic add/update operations. It distinguishes from sibling tools like add/update operations by clarifying the pre-usage context.
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 indicates when to use the tool: before generic add/update operations. However, it does not explicitly exclude alternatives or mention when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the specific database context but does not disclose any additional behavioral traits beyond what annotations provide.
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 with no extraneous words, efficiently conveying the tool's purpose.
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 no-parameter listing tool with annotations covering safety, the description is sufficient. It could optionally mention the return format, but this is not strictly necessary given the simple output.
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?
No parameters are defined, and schema coverage is 100% (trivially). The description does not need to add parameter details; baseline 4 applies for zero-parameter tools.
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 ('List all tables') and the resource ('in user directives database'), using a specific verb and resource that distinguishes it from siblings like get_user_custom_fields or get_core_tables.
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?
No explicit guidance on when to use this tool versus alternatives such as get_core_tables or get_project_tables. The context of 'user directives database' implies a specific scope, but lacks explicit exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds valuable context: it skips non-existent entries and reports modules left empty. This goes beyond annotations without contradicting them.
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 concise sentences, all earning their place. Front-loaded with the action, no wasted words.
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 required parameter and no output schema, the description covers key behaviors (efficiency, skipping, reporting). It lacks return value details, but given the simplicity, it is fairly 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 coverage is 100% with a clear description for the 'links' parameter. The description adds little beyond 'batch' context, so a 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 clearly states 'Batch remove multiple files from modules', using specific verbs and resources. It distinguishes itself from the sibling tool 'remove_file_from_module' by highlighting efficiency for multiple removals.
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 multiple removals by stating it's more efficient than multiple single calls, but it lacks explicit when-to-use or when-not-to-use guidance. No mention of prerequisites or alternatives beyond the single-removal sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds no behavioral traits beyond this; it only reiterates the search purpose. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the action and use case. Every word is functional with no redundancy.
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 8 parameters (all with schema descriptions) and no output schema, the description provides sufficient context for its search purpose. It lacks details about return format but is adequate for a read-only search tool.
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 each parameter well-documented. The description adds no additional meaning to parameters, maintaining the baseline 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 clearly states 'Search past decisions and context by keyword' with specific verb and resource, and provides a use case ('recall why a decision was made'). It distinguishes from sibling search tools by focusing on 'past decisions' and historical context.
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 says 'Use to recall why a decision was made or find historical context,' providing a clear usage context. However, it does not specify when not to use this tool or mention alternatives like search_tracking_notes or search_directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe and side-effect-free. The description adds that it provides a 'full context bundle' or 'watchdog alerts', which is useful operational context but does not disclose new behavioral traits beyond what annotations imply.
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: first states purpose, second details parameter usage. No redundancy, front-loaded, every sentence adds value.
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 description covers purpose and parameter semantics but omits what the tool returns (no output schema exists). For an orchestrator, return value details would be helpful for understanding how to use its output.
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 describes the boolean parameter. The description goes further by linking the parameter values to specific scenarios (true = session start, false = checkpoint), adding meaningful context 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 identifies the tool as a 'main entry point orchestrator' with two specific use cases: session start and work checkpoints. This distinguishes it from the many sibling tools that perform specific CRUD operations or queries.
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 (session start with is_new_session=true, work checkpoints with false) but does not mention when not to use it or provide alternatives. Still, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds that it parses schema to extract constraints, providing useful behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste, front-loaded with key purpose and method.
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 simple read-only tool with two required parameters and no output schema, the description fully covers purpose, behavior, and result.
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%, so parameters are documented. Description adds context about the overall function but does not augment individual parameter meaning 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?
Description clearly states it returns allowed values for CHECK constraint enum fields, specifying the database aimfp_core.db, and distinguishes from siblings that operate on other databases.
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?
No explicit guidance on when to use this tool versus alternatives like project_allowed_check_constraints, though the description implies use for core database constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds the all-or-nothing atomicity and the prerequisite of writing files to disk. It does not clarify reversibility despite destructiveHint=false, but the main behaviors are disclosed.
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 extremely concise: two sentences with no filler. It front-loads the key action and constraints, making every sentence valuable.
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?
Given the simple structure (single parameter, no output schema), the description adequately covers the tool's purpose, prerequisites, and behavioral characteristics. No missing critical information.
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 coverage is 100% with descriptions for the 'files' parameter. The description does not add additional parameter-level meaning beyond what is already 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 clearly states the action ('Batch-finalize'), the resource ('multiple reserved files'), and key constraints ('after writing them to disk', 'all-or-nothing'). It effectively distinguishes from the sibling 'finalize_file' tool by indicating it operates on multiple files as a batch.
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 prerequisite ('after writing them to disk') and behavior ('All-or-nothing'), but does not explicitly guide when to use this tool versus alternatives like 'finalize_file' for single files or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds context about returning names only vs. full data, which clarifies expected behavior beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two targeted sentences: first states purpose, second clarifies scope and use. No redundancy or excess wording.
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?
No output schema is present; description says 'Returns names only' but does not specify format (e.g., array of strings). For a simple list tool, this is adequate but leaves minor ambiguity.
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% with the 'types' parameter fully described. Description briefly echoes filtering by types, but adds no new detail 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?
Clearly states verb ('Get'), resource ('directive names'), and scope ('all' or filtered by types). Distinguishes from sibling 'get_all_directives' by noting it returns names only, not full data.
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?
Explicitly says 'AI queries by name when needs details,' implying the agent should use this tool to get names first, then use 'get_directive_by_name' for details. Provides clear context but does not explicitly list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds the filtering behavior. No contradictions. Some additional behavioral traits (e.g., ordering) could be mentioned, but annotations cover safety.
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 of 7 words, front-loaded with the core action and filtering. No redundant information.
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 simple read-only list tool with one parameter and no output schema, the description is sufficient. It clearly communicates the tool's purpose and filter criterion.
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% with a single parameter 'status' described as 'pending', 'in_progress', 'completed'. The description adds no extra meaning beyond what the schema already provides, so 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 'Get completion paths filtered by status' clearly states the verb (get), resource (completion paths), and filtering criterion. It distinguishes from siblings like 'get_all_completion_paths' and 'get_incomplete_completion_paths'.
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 when filtering by specific status, but does not explicitly mention when to prefer this over alternatives like get_all_completion_paths or get_incomplete_completion_paths. No exclusion criteria or when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is known to be safe. The description does not add behavioral context beyond what annotations provide, such as details about permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no superfluous words. It is front-loaded and efficient.
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 simple parameterless tool with no output schema, the description is sufficiently complete. It specifies the filter condition (is_tool=true), making the tool's purpose fully understandable.
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 input schema has zero parameters and 100% schema description coverage. The description adds no parameter details but also does not need to, as there are no parameters. It adequately states what the tool returns.
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 'Get all MCP tools (is_tool=true)' clearly identifies the tool's function as retrieving tools with a specific flag. It uses a specific verb ('Get') and resource ('MCP tools') and distinguishes itself from sibling tools like get_helpers_are_sub.
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 explains what the tool does but provides no guidance on when to use it versus alternatives like get_helpers_are_sub or get_helpers_by_database. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds value by specifying the scope (unfinished tasks with subtasks and sidequests) and the purpose ('shows remaining work'), which goes beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, concise, and front-loaded with the core action. Every word contributes meaning, with no redundancy or filler.
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 description covers the basic return content (tasks, subtasks, sidequests) and purpose (remaining work), but omits details on the exact structure (e.g., flat list vs. nested) or any output fields. Given the lack of an output schema, more specificity would improve completeness.
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?
With 0 parameters and 100% schema coverage, the baseline is 4. The description correctly adds no parameter details since none exist. It does not need to compensate for missing schema info.
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'), resource ('unfinished tasks'), statuses included ('pending, in_progress, blocked'), and the inclusion of subtasks and sidequests. It distinguishes this tool from siblings like get_incomplete_subtasks or get_tasks_by_milestone by specifying the combined output.
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 (need incomplete tasks with subtasks/sidequests) but provides no explicit guidance on when not to use or how to choose between this and similar tools like get_incomplete_subtasks_by_task or get_incomplete_items. The sibling list is large, but no comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, providing behavioral safety. The description adds only that tasks of any status are returned, which is a minor clarification consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. Every word is necessary, with no redundancy.
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?
Given the simple tool (one integer parameter, read-only, no output schema) and robust annotations, the description provides all necessary context 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 coverage is 100% with 'milestone_id' described as 'Milestone ID'. The description adds no additional meaning beyond the schema, so a 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 clearly states 'Get all tasks for a milestone (any status)', specifying the verb, resource, and scope. It distinguishes itself from siblings like 'get_incomplete_tasks_by_milestone' by noting that tasks of any status are returned.
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 implicitly indicates when to use this tool (when all statuses are needed) versus alternatives like 'get_incomplete_tasks_by_milestone', but does not explicitly name them or provide exclusion criteria. The contextual sibling list supports this inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds return content details (definition_json, description, file location) and usage ordering, which is helpful but not extensive.
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 concise sentence plus a brief hint, front-loading the purpose and adding value without unnecessary words.
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 lookup tool with good annotations, the description provides essential info but lacks guidance on when not to use it or how it relates to sibling search tools, leaving some gap in completeness.
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?
All parameters have clear schema descriptions (100% coverage), so the description adds no new information beyond repeating the return content. It does not explain defaults or behavior further.
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 'Look up' and the resource 'tracked type by name', with additional context ('full definition and file location'). It distinguishes from sibling tools like 'search_types' by focusing on exact name lookup.
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 advises to use this tool 'BEFORE reading source files', providing a clear usage context. However, it does not mention when not to use it or compare to alternatives like 'search_types'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the action deletes the junction entry (a destructive operation on the association) while clarifying the file itself is unaffected. This adds context beyond the annotations (which mark destructiveHint as false, likely referring to the file). No contradiction.
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, both immediately relevant. No wasted words. Front-loaded with the primary action.
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?
Given the tool's simplicity (2 parameters, no output schema), the description covers what the tool does and what it does not do. It is complete for an agent to decide when to invoke it.
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 each parameter's description is already clear. The description does not add additional semantic information beyond what the schema provides. 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?
Description clearly states the tool removes a file from a module by deleting the junction entry, and it explicitly distinguishes that the file itself is not deleted. This differentiates it from sibling tools like 'add_files_to_module' and 'delete_file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 this tool (to remove a file from a module) but does not explicitly state when not to use it or mention alternatives beyond the implication that the file remains. No prerequisites or conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent=true and non-destructive. The description adds context about extending core return_statements and the modify-via-delete pattern, which is consistent and adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first defines the core action, the second adds crucial usage instruction. Every sentence is essential, no fluff.
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 description lacks detail on what happens if the statement already exists (overwrite?) and does not mention return values. Given no output schema, this is a moderate gap for a simple set 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% with all parameters described. The description does not add new meaning beyond the schema; it merely restates the parameter purpose, meeting the baseline for high 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 adds a custom return statement to a helper function, extending core return_statements. It distinguishes from the sibling 'delete_custom_return_statement' by implying the add operation and noting the modification pattern.
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 instructs 'To modify: delete first, then set new statement,' providing clear when-to-use guidance. However, it does not explicitly list alternatives beyond the delete tool, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and idempotent. Description adds cascade completion behavior, which is a valuable side-effect not captured in annotations. No contradiction.
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, each adding value. First sentence defines purpose, second provides important usage guidance. No wasted words.
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?
Description covers key behavioral aspects but omits output expectations. Since there's no output schema, the agent would benefit from knowing what is returned (e.g., updated milestone object or success confirmation). Cascade behavior could also be more detailed regarding failure scenarios.
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% with clear descriptions for each parameter. Description does not add new parameter-level insights beyond the cascade implication for status='completed'. 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?
Description explicitly states 'Update milestone status, name, or description' with a specific verb and resource. The cascade completion behavior distinguishes it from sibling tools like add_milestone and delete_milestone.
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?
Provides clear context for when to use it, especially mentioning cascade completion when completing a milestone. However, it does not explicitly state when not to use it or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds context that it parses the schema to extract constraints. It does not disclose anything beyond what annotations and the simple nature imply, but doesn't contradict.
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 that directly state the action and the method. It is front-loaded with the main purpose, no extraneous words, and highly efficient.
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 simple read-only tool with annotations, a clear name, and complete schema descriptions, the description fully covers what the agent needs to know. The return is a list of allowed values, which is straightforward without needing an output schema.
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 parameters (table, field) described in the input schema. The description adds no additional meaning beyond what the schema provides, so 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 returns a list of allowed values for CHECK constraint enum fields in user_preferences.db, with a specific verb and resource. It distinguishes from siblings like core_allowed_check_constraints by naming the specific database.
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 implicitly indicates use for user_preferences.db based on the name and context, but does not explicitly mention when to use this tool over alternatives like core_allowed_check_constraints. However, the naming makes it clear, so it's fairly clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (no readOnlyHint, no destructiveHint, etc.), so the description carries the burden. It discloses that the tool sets status and timestamp, and explicitly states that deployment is handled elsewhere, adding behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences with zero waste. It front-loads the core action and immediately follows with an important caveat. 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?
For a simple one-parameter tool with no output schema, the description covers the main action and a key non-action. It could mention return value or error conditions, but is mostly complete for its complexity level.
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 description does not add any additional meaning beyond the schema's description for directive_id. Baseline 3 is appropriate as the parameter is well-defined in 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 (Set), resource (directive status), and scope (to 'active' and timestamp). It also explicitly distinguishes from a related action (does not deploy services), differentiating it from other directive workflow tools.
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 by stating what the tool does NOT do ('Does NOT deploy services'), giving a when-not-to-use hint. However, it lacks explicit guidance on when to use this tool versus the sibling deactivate_user_directive or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive behavior. The description adds value by explaining the audit trail nature, typed notes, and optional directive linking. It does not contradict annotations and provides useful context beyond the structured fields.
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, well-structured sentence that immediately conveys the tool's purpose and key features (audit trail, typed notes, directive linking). No redundant or unnecessary 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?
Given the tool's complexity (8 parameters, 2 required) and thorough schema, the description adequately covers purpose and usage context. It does not explain return values, but output schema is absent. The description is sufficient for an agent to decide when to use this tool among many siblings.
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 has 100% coverage with detailed descriptions for all 8 parameters. The description mentions 'typed notes' and 'optional directive linking,' which aligns with note_type and directive_name, but adds little extra meaning beyond what the schema already provides.
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 purpose: recording decisions, architecture changes, or context events in the project's audit trail. It specifies 'typed notes with optional directive linking,' which distinguishes it from sibling note tools like 'add_tracking_note' or 'add_user_directive_note'.
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 by listing example note types (decision, architecture change, context event). However, it does not explicitly state when not to use this tool or mention alternative tools for specific note purposes, though the sibling list implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, and the description adds that the tool performs atomic creation of directories, databases, and templates. This goes beyond annotations by stating it is atomic and mechanical, clarifying the nature of the write operations. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the key information (phase, orchestration, actions) and efficiently communicates scope and nature. 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?
For a single-parameter tool with no output schema and adequate annotations, the description covers the key behavioral aspects (atomic creation, mechanical nature). However, it could be more specific about what 'databases with schemas' and 'templates' entail, and whether there are prerequisites or error behaviors. Nonetheless, it is sufficiently complete for an initialization tool.
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% with one parameter (project_root) fully described in the schema. The description adds general context that the tool uses this root for creation, but does not provide additional parameter-level details (e.g., format requirements, behavior if path already exists). Baseline 3 is appropriate since schema already covers the parameter.
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 it is a 'Phase 1 mechanical setup orchestrator for project initialization' and lists specific actions (creates directories, databases with schemas, templates). It distinguishes itself from siblings like 'create_project' or 'create_state_database' by framing it as an atomic orchestration of multiple setup steps. The phrasing 'No deep logic - pure mechanical operations' further clarifies its scope.
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 it is the first step in project setup ('Phase 1') and should be used for mechanical initialization. However, it does not explicitly state when to avoid this tool or provide alternatives for specific scenarios (e.g., if a user only needs a single component). The context suggests a clear use case but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral insight beyond annotations by stating 'atomically' and implying transactional integrity. Annotations already indicate non-destructive and non-idempotent behavior, but atomicity is a key additional trait disclosed here.
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 extremely concise with two sentences. The first sentence states the purpose, the second provides usage context. No superfluous words, effectively front-loaded.
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 three parameters and no output schema, the description covers the core purpose and usage context adequately. It does not detail return values or error handling, but given the annotations and schema, it is sufficient for an agent to use the 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?
Schema coverage is 100%, so all parameters have descriptions. The tool-level description does not add extra meaning to parameters beyond what the schema provides, hence baseline score 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 clearly states the tool updates multiple project items atomically, with a specific verb ('Update') and resource ('project items'). It distinguishes itself from siblings by emphasizing atomicity and batch operation, which is not available in individual update tools.
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 context: 'Used after code generation or bulk operations to ensure consistency.' This tells the agent when to use it, but it does not explicitly mention when not to use it or list alternative tools like individual updates. However, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal with readOnlyHint=false et al. The description adds value by stating it 'Triggers interaction and type-function checks for all,' which is behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. Front-loaded with the primary purpose.
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?
No output schema, but the description covers the key purpose and triggers. Could mention expected return value or error conditions, but adequate given tool 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 input schema already provides full description for the 'functions' parameter (100% coverage). The tool description does not add further meaning, so baseline 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 clearly states 'Batch-finalize multiple reserved functions after writing them,' specifying the action (batch-finalize), the resource (reserved functions), and the context (after writing). It distinguishes from siblings like finalize_function (singular) and finalize_types.
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 (after writing reserved functions) but does not explicitly state when not to use or provide alternatives like finalize_function for single function finalization. Still, context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read. The description adds that it queries by status, but does not disclose additional behavioral traits like pagination, ordering, or response format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted words. Every word serves a purpose, making it concise 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?
The description hints at the output (active directives and count) but does not specify the structure of the returned data. Given the tool's simplicity and lack of output schema, this is mostly adequate, though mentioning the return format would improve completeness.
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?
There are no parameters (100% schema coverage), so the description need not add parameter details. It implicitly defines the filter (status='active'), which is sufficiently clear. Baseline of 4 is appropriate for zero-parameter tools.
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 ('Get'), the resource ('user directives'), and the filter ('status='active''). It distinguishes from siblings like get_all_directives by specifying the active status filter, making the tool's purpose precise and 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 provides a clear use case ('Convenience query for checking active directive count') but does not explicitly state when not to use it or mention alternatives. It implies a specific context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations by detailing that it returns function signatures and can avoid file opening. Annotations already declare readOnlyHint and idempotentHint, which are consistent.
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-loaded with the primary purpose, no redundant information. Every sentence 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?
Adequate for a read-only, idempotent tool: states what it returns, when to use, and is consistent with annotations. Could mention return format but not required given the tool's simplicity.
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 description does not add significant meaning beyond parameter names and defaults. The description implies signature details but the schema already covers parameter roles.
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 'Get all tracked function signatures for a file' with a specific verb and resource. It also distinguishes from reading source code, making it clear what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'use BEFORE reading source code' and 'often provides everything needed without opening the file,' giving clear context for when to use. Does not explicitly exclude alternatives but is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate them. It adds behavioral context by framing the tool as for understanding dependency roles, which provides insight beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a dash, extremely concise with no wasted words. Every part 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 tool with only one parameter, no output schema, and annotations covering safety, the description is quite complete. It explains both the action and the purpose. It slightly lacks details about return format, but that is not heavily demanded given the simplicity.
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%, so the description does not need to add parameter details. The description does not add any meaning beyond what the schema already provides for 'file_id'. 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 states a specific verb+resource: 'Get all interactions for functions in a file'. It also adds a distinct purpose: 'understand file's dependency role'. This clearly distinguishes it from the sibling 'get_interactions_by_function', which focuses on a single function.
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 usage for understanding a file's dependency role, but does not explicitly state when not to use it or mention alternatives like 'get_interactions_by_function'. The context is clear, but lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false. Description adds context: creates fresh DBs, transfers via ATTACH, returns temp paths for verification. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with main action and brief process. Every sentence 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 one simple parameter, no output schema, and basic annotations, the description adequately explains the tool's behavior (creation, transfer, temp paths). Could mention if old databases are modified.
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?
Single parameter 'aimfp_folder' with schema description 'AIMFP project directory name' and default. Description does not add further meaning beyond schema. Baseline 3 since schema coverage is 100%.
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 uses specific verb 'migrate' and resource 'pending project databases' with clear action: creates fresh DBs and transfers data. Distinguishes from sibling tools like 'create_state_database' or 'get_databases'.
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?
Describes the migration process and outcome (creates fresh DBs, transfers data, returns temp paths). Provides context for when to use but doesn't explicitly mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it provides 'powerful filtering and joining capabilities without writing raw SQL', giving context about the abstraction level and safety.
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, both concise and front-loaded. Every word adds value with no redundancy or fluff.
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 complexity (6 params, nested objects) and lack of output schema, the description adequately characterizes the tool's role among many sibling tools. It could mention output format but is generally 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 coverage is 100% with detailed descriptions for all 6 parameters. The description does not add additional meaning beyond what the schema already provides, so baseline score 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 'SQL-like query interface for complex project queries', specifying verb (query) and resource (project state). It avoids tautology and distinguishes from sibling tools like get_project and query_core by emphasizing 'project' and 'complex queries'.
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 indicates it is for complex queries on project data, implying it should be used when simple getters are insufficient. However, it does not explicitly state when not to use it or list alternatives, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe read operation. The description aligns by calling it a query and specifying the database. No contradictions, and the description adds the 'advanced' caveat, but does not disclose potential risks like SQL injection or table existence constraints.
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 conveys essential purpose and usage context without any wasted words. It is front-loaded 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 read-only query tool with annotations covering safety, the description is fairly complete. It identifies the database and the advanced nature. No output schema exists, but the tool's purpose is sufficiently clarified for an agent to decide when to invoke it.
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%: both parameters (table, where_clause) are described. The description adds 'complex SQL WHERE clause' but does not provide new semantic information about the parameters themselves 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 'Execute complex SQL WHERE clause on user_directives.db (advanced, rare use)' clearly states the action (execute), resource (SQL WHERE clause on a specific database), and usage context (advanced, rare). It distinguishes from simpler tools like get_from_user_custom_where.
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 phrase 'advanced, rare use' implies that this tool should be used when simpler query tools are insufficient, but it does not explicitly state when not to use or mention alternatives. The guidance is present but could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (no readOnly, not destructive), so the description carries the burden. It adds that each function should include purpose/parameters/returns, which is helpful. However, it does not explain what 'reserve' entails (e.g., locking, allocation) or side effects beyond reservation.
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 18-word sentence, efficient and front-loaded. It wastes no words and clearly conveys the action and data requirements.
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 tool's simplicity (one parameter, no output schema), the description is largely sufficient. It could briefly mention the return value (e.g., 'returns reserved IDs'), but the absence is not critical for a straightforward batch 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 coverage is 100% with one parameter. The description adds value by specifying that each function object must include 'purpose/parameters/returns', which goes beyond the schema's field names. This guides the agent on required content.
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 ('Batch-reserve function IDs'), the resource ('function IDs'), and the context ('before writing multiple functions'). It distinguishes this tool from siblings like 'reserve_function' (singular) and other reserve tools.
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 says 'before writing multiple functions', indicating when to use. Although it doesn't mention when not to use or name alternatives explicitly, the batch vs singular distinction is clear from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description aligns with these by describing a search/find operation. It adds context about the search criteria but no additional behavioral traits beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose and usage context. No extraneous 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?
Given the simple nature of the tool, the description provides sufficient context for selection. Parameters are well-documented in the schema, and the usage scenario is clear. However, it could briefly mention return format or limits, but not required for a search tool.
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% for all three parameters. The description does not add any meaning beyond what the input schema provides, so 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 'find', the resource 'directives', and the scope 'by type, category, or keyword'. It distinguishes from siblings like 'get_directive_by_name' which requires exact name.
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 a clear usage scenario: 'when you know the domain but not the exact directive name'. It implies when to use, but does not explicitly list exclusions or alternatives among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the specific search method (FTS5 full-text search with relevance ranking), providing behavioral detail beyond annotations. No contradiction.
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?
Single sentence, 13 words, front-loaded with key verb and resource. Every word earns its place — no filler or redundancy.
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 3-parameter search tool without output schema, the description covers search mechanism and ranking. It does not detail return format or pagination, but given the simplicity and annotations, it's mostly 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 coverage is 100% with descriptions for all 3 parameters. The description mentions 'search by name or purpose', which aligns with search_string but adds no new parameter-level meaning. The mention of 'relevance ranking' gives context but doesn't enhance parameter semantics directly. 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?
Description starts with 'Search tracked functions' — a specific verb and resource. Qualifies with 'by name or purpose using FTS5 full-text search with relevance ranking', clearly differentiating from sibling search tools targeting other entities (directives, modules, notes, etc.).
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 implicitly states usage for searching functions. No explicit when-not or alternatives, but the context of sibling tools makes it clear that similar tools exist for other entities. A small improvement would be to mention alternatives, but not required for clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, non-destructive. Description adds that it updates specific fields and is used for progress marking. Consistent with annotations; no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. First sentence states core functionality, second provides key use case. Front-loaded 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 update tool, description suffices for selection. Lacks return value information (no output schema), but the schema is rich and annotations cover safety. Good enough given 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?
Schema coverage is 100% with descriptive property comments. Description merely lists the three updatable fields without adding semantics beyond what schema already provides (e.g., status values). Baseline 3 justified.
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?
Clearly states verb 'update' and resource 'single item', specifies fields (status, name, description), and distinguishes from siblings like 'update_items' and 'delete_item' by focusing on single item. Includes primary use case (marking progress).
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?
Provides primary use context (marking in_progress/completed), implying when to use. Lacks explicit exclusion or alternatives, but siblings like 'update_items' imply batch use. No prerequisites or when-not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral detail by mentioning that it 'parses schema to extract CHECK(field IN (...)) constraints,' providing transparency into how the tool works without contradicting 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?
Two sentences, front-loaded with the primary action. Every sentence adds value, and there is no fluff.
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 description adequately explains the purpose and behavior. However, it lacks details about the return format (e.g., list of strings) and potential errors. Given the simplicity of the tool, this is a minor 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%, and the schema already describes both parameters clearly. The description does not add further semantics beyond what the schema provides, so 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 ('returns') and the specific resource ('allowed values for CHECK constraint enum fields') with a specific database scope ('user_directives.db'). It distinguishes from sibling tools like 'core_allowed_check_constraints' and 'project_allowed_check_constraints' by specifying the database.
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 the tool should be used for CHECK constraints in user_directives.db, but does not explicitly state when to use it versus alternatives or provide any exclusions. However, the context of sibling tools makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are neutral (non-destructive, non-read-only). The description adds critical behavioral detail: deactivation does not stop services, which is beyond what annotations provide.
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, each earning its place. No redundant information. Front-loaded with purpose and key caveat.
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 simple tool with one parameter and no output schema, the description fully covers what an agent needs: action, effect, and behavioral constraint.
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% with a clear description for directive_id. The description adds no extra parameter detail beyond the schema, so baseline 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 clearly states the tool sets directive status to 'paused' and differentiates from stopping services. It also implies distinction from activate_user_directive sibling.
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 (pausing directive without stopping services) but does not explicitly list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read-only behavior. The description adds useful context: sorting by name and returning a list, which goes beyond annotation information.
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?
Extremely concise: two short sentences, no wasted words. Front-loaded with the core purpose immediately.
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 parameterless tool with no output schema, the description provides all necessary context: what it returns (list of module records) and ordering (sorted by name). Fully adequate.
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?
No parameters exist in the schema, so the description does not need to explain parameters. Baseline score of 4 applies as there is no missing information.
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 clearly states the tool's purpose: 'Get all modules in the project' and specifies the output format 'list of all module records sorted by name.' Effectively distinguishes it from sibling tools like get_module_by_name or get_module_by_path.
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?
Usage is implied but not explicitly stated. The description does not mention when to use this tool vs alternatives or when not to use it. For a simple retrieval tool, this is adequate but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description adds usage sequencing and return type details, enhancing 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 concise sentences with front-loaded key info; no superfluous content.
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 simple 1-parameter read-only tool, the description covers purpose, usage, and return value completely, despite no output schema.
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 parameter, and the description doesn't add extra meaning beyond the schema's description. Adequate but not enhanced.
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 specifies a clear verb ('Look up') and resource ('tracked file by path'), distinguishes from siblings like 'get_file_by_name', and mentions the output (metadata and ID).
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?
Explicitly advises using the tool 'BEFORE reading source files', providing clear sequencing context. No exclusion of alternatives, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, which cover safety. Description adds useful context about being lightweight and returning only names, but does not disclose further behavioral aspects like pagination or performance. It adds value without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single 12-word sentence that clearly conveys purpose. No extraneous information. Front-loaded and efficient.
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 no-parameter tool with rich annotations, the description fully explains the output (names grouped by category) and its lightweight nature. No output schema required; the description suffices.
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?
Tool has zero parameters, and schema description coverage is 100% trivially. Per guidelines, baseline is 4. Description adds no parameter info because none are 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?
Description clearly states it retrieves a 'lightweight FP directive index grouped by category (names only, not full definitions)'. The verb 'get' and specific resource are clear. It differentiates from siblings like get_all_directives and get_directives_by_category by specifying lightweight and names-only.
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 usage when a concise index of directive names by category is needed, but does not explicitly exclude when full definitions or ungrouped lists are required. With many sibling tools, explicit when-not guidance would improve, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety traits. It adds value by specifying that the tool returns 'purpose, parameters, returns, and file path', which is behavioral context beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the action ('Look up') and immediately provides the usage hint and return information. Every part of the sentence is informative and 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?
Given the parameters (3, all with schema descriptions), rich annotations (readOnlyHint, idempotentHint), and no output schema, the description adequately covers what the agent needs: the tool's purpose, when to use it, and what it returns. No gaps are apparent.
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 has 100% description coverage, so the parameters are well-documented in the schema itself. The description does not add new meaning to individual parameters beyond what the schema provides, but it does set overall context for when to use the parameters. 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 action ('Look up'), the resource ('tracked function by name'), and the returned data ('purpose, parameters, returns, and file path'). It also includes a usage hint ('use BEFORE reading source files'), which distinguishes it from sibling lookup tools like search_functions or get_functions_by_file.
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 advises to use this tool before reading source files, providing a clear usage context. It does not explicitly mention when not to use or name alternatives, but the timing guidance is actionable and helps the agent sequence operations correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is clear. The description adds context about the template being for adaptation but does not disclose additional behavioral traits beyond what annotations provide.
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-loaded with the action, no wasted words. Every sentence adds value.
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 simple tool with no parameters and no output schema, the description fully explains what it returns and its purpose. It is complete given the low complexity.
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?
No parameters exist, so baseline is 4. The description does not need to add parameter info. Schema coverage is 100%.
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 it returns the Python state_operations.py template content for AI to adapt, specifying the resource and action. It distinguishes from sibling get_* tools by referencing the template and CRUD helper for .state/runtime.db.
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 tells when to use: to retrieve the CRUD helper template. However, it does not provide when-not-to-use or alternative tools, but the context is clear given the tool's specific purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, fully covering the behavioral safety profile. The description adds the detail that it retrieves from the 'user_settings table' and returns all settings, which is consistent and non-contradictory.
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, front-loaded sentence that efficiently states the verb, resource, and relationship to the sibling tool with no wasted words.
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?
Given zero parameters and no output schema, the description, combined with annotations, is complete for understanding the tool's purpose and behavior. It clearly specifies the data source and the sibling tool for single-key access.
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 (input schema empty), so schema description coverage is 100%. The description adds value by specifying that it returns 'all user settings', which clarifies the scope 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 all' and the resource 'user settings from user_settings table', and explicitly distinguishes it from the sibling tool 'get_user_setting' by noting it gets all settings versus a single setting by key.
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 on when to use this tool (to get all settings) and explicitly names the alternative sibling tool 'get_user_setting' for getting one setting by key, but does not mention any conditions when not to use it or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds behavioral context by noting it's a mandatory step that returns an ID to embed. No contradiction with annotations, and it clarifies the role in a multi-step process beyond what annotations provide.
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, front-loaded with the core action. Every word adds value: verb, resource, flow context, and return value. No fluff.
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?
Given no output schema, the description explicitly mentions the return value (ID). Parameter coverage is full. The description explains the tool's role in a higher-level workflow, making it complete for an agent to understand when and how to invoke it.
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 each parameter is already documented. The description adds general context ('Returns ID to embed') but does not enhance individual parameter understanding 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 verb 'Reserve' and the resource 'file ID', and situates it within the 'mandatory reserve-write-finalize tracking flow'. It distinguishes itself from siblings like 'reserve_files' (plural) and 'finalize_file', 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'before writing code' and 'part of the mandatory ... flow', providing clear when-to-use context. It doesn't explicitly state when not to use it or name alternatives, but the flow context is sufficient for guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false; the description adds that it returns IDs in input order for embedding, which is helpful behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.
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?
Given the simple parameter schema and presence of annotations, the description is complete, explaining the batch nature, ordering, and purpose for embedding filenames.
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% with a single parameter fully described. The description does not add significant meaning beyond the schema, baseline 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 clearly states 'Batch-reserve file IDs before writing multiple files' with a specific verb (reserve) and resource (file IDs). It distinguishes from siblings like 'reserve_file' by indicating batch 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 provides context 'before writing multiple files' but does not explicitly state when not to use it or mention alternatives like reserve_file for single files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context by disclosing the search algorithm (FTS5 ranked with LIKE fallback), which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. Efficiently communicates the tool's functionality and search mechanism.
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 simple search tool with one parameter and no output schema, the description is fully complete. It covers what is searched and how the search works.
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 schema provides parameter description 'Search term' with 100% coverage. The description adds meaning by specifying the fields searched (name, purpose, description), enhancing the agent's understanding.
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 searches modules by name, purpose, or description. It uses specific verbs and resources, distinguishing it from sibling tools like search_functions or search_types.
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 provides technical details (FTS5, LIKE fallback) but does not explicitly state when to use this tool over alternatives or when not to use it. It is implied for module searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=false, so the description's 'Update' is consistent. No additional behavioral traits (e.g., safety, side effects) are disclosed beyond what annotations provide, leading to a baseline 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, concise sentence with no wasted words. It front-loads the action and target, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description fully explains what it does. No additional context is necessary.
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 and schema coverage is 100%. The description does not need to add parameter information, and with 0 params a score of 4 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 'Update project.last_known_git_hash with current Git HEAD' clearly states the specific action and target resource, distinguishing it from any sibling tools that update other fields.
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: when the git hash needs syncing. No explicit when-not or alternatives, but the specificity makes it clear. Siblings like 'update_project' exist but target broader fields, so context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which declare non-destructive, not read-only), the description adds valuable behavioral details: silently skipping duplicates and failing fast on missing entities, which informs the agent of side effects and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words; critical information is front-loaded. Perfectly 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?
The tool is simple with one parameter and no output schema. The description covers behavior and efficiency, but could optionally explain the return value or error handling details for completeness.
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% with a single parameter 'links' described as a list of tuples. The description adds no extra semantic detail beyond the schema, so 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 verb 'assign' and resources 'files to modules' and explicitly distinguishes from sibling 'add_file_to_module' by stating it is a batch version.
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 notes efficiency over multiple single calls and mentions duplicate handling and error behavior, but does not explicitly say when not to use it or provide alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the full burden. It adds key behavioral context: 'pauses the current task' and 'urgent interruption,' which discloses side effects beyond what annotations provide.
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 extremely concise (two sentences) and front-loaded with the primary action. 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?
For a tool with 7 parameters and no output schema, the description covers core usage and context. It omits details like default values but those are in the schema. Overall, it sufficiently guides the agent.
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%, so the schema already documents all parameters. The description adds no additional parameter-level meaning, earning a baseline score 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 clearly states the tool creates an urgent interruption that pauses the current task, specifying verb (create) and resource (sidequest). It distinguishes from siblings like add_task and add_subtask by emphasizing urgent interruptions.
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 use cases: bug fixes, blockers, or unexpected work discovered mid-task. It implies not for planned work, but does not explicitly exclude other scenarios or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide limited behavioral hints, but the description adds important context: reminders persist until cleared, and the tool must be called after handling findings. This discloses the mutation behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action, then providing necessary context. No extraneous words; every sentence adds value.
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?
The description fully explains the tool's effect, persistence behavior, and prerequisites. Given the simplicity (no output schema, no params), it is complete.
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?
With no parameters in the input schema, the description does not need to elaborate. It correctly focuses on the tool's purpose, and the baseline for 0 params is 4.
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 ('Clear') and resource ('watchdog reminders'), with a specific verb-resource combination. It does not explicitly differentiate from siblings, but 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 Guidelines5/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 ('after addressing all watchdog findings') and what happens if not called ('reminders persist until this is called'), providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so description is not burdened. It adds context that themes are 'high-level architectural areas', which aids understanding of the domain. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the action verb first. No superfluous information. Every word serves a purpose.
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 parameters and no output schema, the description covers the essential purpose and usage context. Could mention the return format (e.g., list of theme names) but not critical for a read-only tool with annotations.
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?
No parameters exist, schema coverage is trivially 100%. Description need not expand on parameters. Baseline of 4 is appropriate for a zero-parameter tool.
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?
Clearly states the tool retrieves all project themes, defining themes as 'high-level architectural areas'. The verb 'get' and resource 'themes' are specific. Distinguishes from siblings like 'get_all_flows' or 'get_all_modules' by targeting a distinct entity.
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?
Provides a usage scenario: 'Use to orient on project structure before starting work.' This implies context but does not specify when not to use or offer alternatives. Clear enough for a simple retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing that when project_root is provided, it retrieves preferences from user_preferences.db and linked notes from project.db. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the purpose concisely, and the second provides a critical usage instruction. Every word is justified, and the most important guidance is front-loaded.
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 two parameters and no output schema, the description covers what is loaded (workflow steps, preferences, linked notes) and conditional behavior. It is complete enough for an agent, but lacks explicit mention of the return format or structure.
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%, with both parameters described in the schema. The description adds meaning by explaining the conditional behavior of project_root (retrieving additional data), which is not fully captured in the schema descriptions.
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 'Load' and the resource 'directive's workflow steps, preferences, and linked notes by name.' It distinguishes from siblings like get_directive_content by emphasizing it as the authoritative source to call before executing any workflow.
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 instructs 'ALWAYS call BEFORE executing any workflow' and states 'directives are the authoritative source, not memory,' providing strong contextual guidance. However, it does not explicitly mention when not to use this tool or list specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true. The description adds behavioral details: stops a watchdog process, gathers specific audit data (watchdog state, reminders, files, functions, notes, task state), and returns structured data for AI interpretation. It confirms the destructive action and explains what is gathered, going beyond the annotation.
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, using a few sentences to cover purpose, actions, and key details. It front-loads the purpose ('Session termination orchestrator') and avoids unnecessary words.
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?
Given no parameters and no output schema, the description fully explains what the tool does (end session, gather audit data, stop watchdog) and what it returns (structured audit data for AI to interpret). It provides sufficient context for an AI agent to use the tool correctly.
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 with 100% schema coverage. The description adds no parameter semantics, but none are needed. Baseline for no parameters is 4.
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 it is a session termination orchestrator that gathers audit data. It specifies actions: reading watchdog state, querying files and functions, reading notes and task state, stopping the watchdog, and returning structured data. It distinguishes from siblings by describing its specific orchestration role at session end.
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: use at session termination. It explicitly says 'No analysis logic — AI determines what is stale or missing,' implying the AI should use the output for analysis. However, it does not explicitly state when not to use or compare to alternative tools like aimfp_init or aimfp_run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations indicating destructiveness, the description reveals that CASCADE removes junction entries but files are not deleted, providing essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences with front-loaded purpose, no wasted words.
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 simple delete tool with one parameter, the description fully covers behavior and side effects; no output schema needed.
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% with clear parameter description; the tool description adds no additional meaning beyond the schema for the parameter.
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 'Delete a module' and specifies the cascade behavior, distinguishing it from other delete tools like delete_file which delete 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 delete a module while preserving files) but does not explicitly state when not to use it or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying that returns include standard fields 'even if empty' and returns a 'complete infrastructure table'. This goes beyond what annotations provide, but does not mention potential volume limits or pagination behavior.
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-loaded with the action and scope, followed by purpose. Every sentence is informative and earns its place. No wasted words.
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?
Given zero parameters, no output schema, and annotations covering safety, the description is complete. It states what the tool returns and its typical use cases, enabling an AI to select and invoke it appropriately.
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?
There are zero parameters, so the input schema fully describes the parameters. The description does not need to add parameter information. Baseline for 0 parameters is 4, correctly applied.
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 'Get all infrastructure entries', using a specific verb and resource. It distinguishes from siblings like get_infrastructure_by_type by emphasizing 'all' and 'including standard fields (even if empty)'. 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 provides explicit usage context: 'for session bundling and status reports'. It implies when to use the tool but does not explicitly contrast with similar tools like get_infrastructure_by_type. No alternatives are mentioned, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond annotations by explaining it does not write files, returns JSON with target path, and is derived live from tool registry to avoid drift. Consistent with readOnlyHint and idempotentHint.
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 plus a usage directive, all front-loaded and concise. Every sentence adds value with no waste.
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 simple tool with one optional parameter and no output schema, the description adequately covers behavior, output format, and usage context. No gaps.
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% with a clear parameter description. The tool description adds some merge context, but does not substantially improve on 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?
Clearly states it returns the Claude Code allowlist for pre-approving AIMFP MCP tools. Uses specific verbs and resource, and distinguishes itself from siblings by its unique purpose.
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?
Explicitly says when to call: 'when the user asks to set up AIMFP permissions or skip approval prompts.' No explicit alternatives or when-not-to-use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations (readOnlyHint, idempotentHint) by revealing internal steps: resolves md_file_path from database, reads file, returns content plus absolute path and token estimate. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, no wasted words. Efficient and clear.
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?
Despite no output schema, the description explicitly lists return fields (content, absolute path, token estimate). The parameter is single and simple, and the tool's purpose is fully covered.
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% with a clear parameter description. The tool description adds context about how the parameter is used (resolving path) but does not add new constraints or format details 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?
Description clearly states the action ('Read and return the full MD documentation file') and the resource ('for a directive'). It specifies the output content, distinguishing it from sibling tools like 'get_directive_by_name' which likely returns metadata.
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?
Description implies when to use: when you need the full markdown documentation content. However, it does not explicitly state when not to use or name alternatives, such as 'get_directive_by_name' for metadata-only retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety and idempotency are covered. The description adds that flows are 'architectural groupings describing intended behavior', providing extra behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The verb 'Get' is front-loaded, and the description efficiently conveys the purpose and usage guidance. 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?
Given zero parameters and no output schema, the description is largely complete. It explains what flows are and when to use the tool. The return format is not described, but for a simple list tool this is acceptable. Could be slightly improved by noting typical structure of returned data.
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?
There are no parameters, and schema coverage is 100%. The description explains what flows are, which adds meaning beyond the empty schema. The baseline for zero parameters is 4, and the description meets 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?
The description clearly states 'Get all project flows' with a specific verb and resource. It distinguishes itself from sibling tools like get_flow_by_name by emphasizing 'all' and providing context that flows are architectural groupings. The instruction to check before starting any task reinforces its unique purpose.
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 explicitly says 'Check BEFORE starting any task to understand the architecture', providing clear guidance on when to use this tool. It implies usage for initial architectural understanding, and the context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations (readOnlyHint, idempotentHint) by explicitly stating the tool does NOT write anything, returns prompt text + target path + placement policy, and explains the AIMFP guarantee of never writing outside .aimfp-project/. It also describes consolidation behavior for large existing files.
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 well-structured paragraph. Every sentence contributes essential information without redundancy. It 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter, strong annotations, and no output schema, the description covers purpose, usage, parameter behavior, and safety guarantees comprehensively. No gaps remain.
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 single parameter 'existing_content' is already fully described in the schema (100% coverage). The description adds context by explaining why to pass it: so placement guidance can account for size/consolidation. This adds meaning 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 tool returns the AIMFP system prompt plus target path and placement policy. The verb 'Returns' is specific, and it distinguishes this read-only operation from sibling tools like 'add_*' or 'update_*' that modify state.
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 specifies that the tool is intended as the first move for plugin installs, and clarifies that the AI should call this and then write the file. It does not explicitly list when not to use it or alternatives, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![aimfp MCP server](https://glama.ai/mcp/servers/aryanduntley/aimfp/badges/card.svg)](https://glama.ai/mcp/servers/aryanduntley/aimfp)

Score Badge

Copy to your README.md:

[![aimfp MCP server](https://glama.ai/mcp/servers/aryanduntley/aimfp/badges/score.svg)](https://glama.ai/mcp/servers/aryanduntley/aimfp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aryanduntley/aimfp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server