Hokmah

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is free (zero LLM tokens) and lists outputs, but does not mention side effects, destructive behavior, or permission requirements. Since it's a read-like analysis tool, the lack of destructive warnings is acceptable, but more detail on how the analysis works would improve transparency.

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

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

The description is extremely concise: two sentences with no wasted words. The first sentence states the purpose and outputs; the second adds a unique selling point (free). Every sentence earns its place.

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

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

Given the tool's complexity (3 parameters, output schema present), the description is mostly complete. It explains what the tool returns, which is crucial since an output schema exists. However, it could mention that the analysis is based on the provided 'query' and 'repo_url' to clarify usage context. The presence of an output schema reduces the need to describe return values, so a 4 is justified.

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

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

Schema description coverage is 0%, meaning the description must compensate. However, the description does not explain the parameters beyond what the schema provides (e.g., 'repo_url', 'query', 'branch'). The baseline is 3 for 0% coverage, and the description adds no additional meaning, so a 3 is appropriate.

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

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

The description clearly states the action ('Analyze impact of a code change') and the specific outputs ('Returns risk score, affected files, invariants'). It differentiates from sibling tools like hokmah_generate_code and hokmah_generate_tests, which focus on generation rather than analysis.

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

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

The description implicitly indicates when to use (for impact analysis of code changes) but does not explicitly state when not to use or provide alternatives. The mention of 'FREE — zero LLM tokens' is a unique usage guideline that encourages use.

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

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

The description lacks details on behavior beyond the basic action. It does not disclose authentication needs, rate limits, side effects, or what happens on failure. Since no annotations are provided, the description carries the full burden, which it fails to meet.

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

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

The description is very short (one sentence) and includes 'FREE.', which is promotional and not helpful for tool invocation. It could be slightly more informative without increasing length.

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

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

Given the tool has an output schema and 4 parameters (2 required), the description is insufficient. It does not explain what 'connect' means, what the return value represents, or how the server becomes available for orchestration.

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

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

With 0% schema description coverage, the description should compensate, but it only mentions 'server_url' and 'server_name' implicitly through the action. It provides no details on 'tenant' or 'project' (both have defaults, but no explanation of their role), leaving the agent to guess.

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

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

The description clearly states the action ('Connect an external MCP server') and the resource ('Hokmah'), and the phrase 'for universal tool orchestration' hints at the purpose. However, it does not differentiate from sibling tools like 'hokmah_connect_project', 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.

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

There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., the server must be running) or when not to use it, leaving the agent without context for appropriate invocation.

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

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

With no annotations provided, the description carries full burden. It mentions it 'builds' artifacts and is 'FREE', but does not disclose if the operation is destructive (e.g., overwrites existing data), requires authentication, has rate limits, or what happens to existing graphs. The word 'connect' implies a one-time setup, but no side effects are described.

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

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

The description is two sentences, concise and front-loaded with the main action. However, the word 'FREE' is potentially unnecessary and could be misleading (free as in cost or free as in unrestricted?). Still, it earns its place by adding a notable trait.

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

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

Given the complexity (building multiple graphs from commit history) and an existing output schema, the description does not explain what the tool returns or any side effects. The output schema exists but is not described, leaving the agent uncertain about the response format.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'repo_url' is required but provides no details about the 'branch' parameter (e.g., default is 'main', but not explained). Since there are only 2 parameters and the description adds minimal meaning beyond the schema, a baseline of 3 is appropriate.

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

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

The description clearly states the action (connect a GitHub repo to Hokmah) and the specific deliverables (TransitionGraph, IdeaGraph, WorldModel from commit history). This distinguishes it from siblings like hokmah_analyze which presumably analyzes without connecting.

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

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

No guidance on when to use this tool vs alternatives. For example, how does it differ from hokmah_connect_mcp? No prerequisites or exclusions are mentioned, leaving the agent to infer usage 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.

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

No annotations provided, so description must cover behavioral traits. It mentions 'reduces hallucination via graph context' and 'PRO — requires API key,' which are useful. However, it does not disclose side effects, performance characteristics, or error handling.

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

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

Three short sentences, each with a distinct purpose: purpose, benefit, and requirement. No fluff, but could be slightly more structured.

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

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

The output schema exists, so return values need not be explained. But with 4 parameters and no description of their semantics or how they interact, completeness is moderate.

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

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

Schema description coverage is 0%, so description must compensate. It only mentions that an API key is required (PRO), but does not explain the role of repo_url, query, or branch beyond what schema names provide.

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

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

The description states 'Generate code with architectural memory' which specifies a verb and resource clearly. It differentiates from siblings like hokmah_analyze and hokmah_generate_tests by focusing on code generation with architectural memory.

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

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

The description implies use for code generation tasks requiring architectural context, but does not explicitly state when to use this tool versus alternatives like hokmah_analyze. No when-not-to-use guidance is given.

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

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

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether tests are written to disk, authentication beyond API key, rate limits, or cost implications of '40x fewer tokens'. The mention of 'PRO' hints at access control but lacks detail.

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

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

The description is very concise with only 13 words in two sentences. Every sentence adds value: first states purpose, second highlights efficiency and access requirements. No fluff.

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

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

Given 4 parameters (0% schema coverage), no annotations, and no explanation of return values despite having output schema, the description is incomplete. It lacks guidance on how 'query' influences test generation, what the output looks like, and whether the tool is safe or destructive.

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

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

Schema description coverage is 0%, so description must add meaning. It only mentions 'api_key' is required implicitly via 'PRO — requires API key', but does not explain 'repo_url', 'query', or 'branch'. The description adds no semantic value for 4 parameters.

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

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

The description clearly states the tool generates tests from an architectural graph, with a specific verb 'Generate' and resource 'tests from the architectural graph'. It distinguishes from siblings by mentioning '40x fewer tokens' and 'PRO — requires API key', but does not explicitly differentiate from hokmah_generate_code.

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

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

The description provides no guidance on when to use this tool versus alternatives like hokmah_generate_code. It mentions the PRO requirement and API key, but fails to clarify conditions for use, prerequisites (e.g., existing architectural graph), 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.