PermitPilot

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds minimal behavioral context beyond the trigger scenario, and does not describe the exact output or how the tool processes inputs. This is adequate given the strong annotations, though more detail would help.

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 a single, front-loaded sentence that immediately states the intended use case. Every word earns its place, and there is no irrelevant detail or redundancy.

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

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

Despite having annotations and an output schema, the critical missing piece is input parameter semantics. With 0% schema coverage and no param explanation, an agent cannot reliably determine how to fill 'lane' and 'text'. The description also doesn't address alternative tools or any constraints, leaving the overall context incomplete for a tool that requires two parameters.

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

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

The input schema provides only parameter names 'lane' and 'text' with no descriptions, and the schema description coverage is 0%. The description gives no explanation of what these parameters mean or how they relate to generating inspection questions. The agent has no guidance on what values to pass, making correct invocation highly guess-dependent.

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

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

The description clearly identifies the tool's function: produce questions to verify inspection requirements. While it doesn't explicitly use the verb 'build', the purpose is unambiguous. It distinguishes from siblings by topic (inspection questions vs. opening plans, permit checklists, likely forms).

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 a clear 'use this when' condition: when a user wants questions to verify inspection requirements. It does not explicitly exclude alternatives or name sibling tools, but the context is sufficient for an agent to select it over the listed siblings, which cover different inspection-related tasks.

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 uses the verb 'create', which implies a write operation, while the annotations declare readOnlyHint=true. This is a direct contradiction. No additional behavioral context such as side effects or return format is provided, so the tool's behavior remains unclear and inconsistent.

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 one sentence, front-loaded with the usage scenario, and contains no redundant information. It is concise and well-structured, though it lacks necessary detail for effective use.

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

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

The description gives a high-level use case but omits parameter semantics and contains an annotation contradiction. For a tool with two undocumented parameters, this is insufficient for correct invocation, even with an output schema present.

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

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

The input schema has two parameters (lane and text) with 0% description coverage, and the description does not mention either parameter. Since schema coverage is 0%, the description must compensate but fails entirely, leaving the agent without any guidance on parameter meaning.

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 creates a project-opening plan from permit dependencies, using a specific verb and resource. It doesn't explicitly differentiate from sibling tools, but the purpose is understandable.

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 begins with 'Use this when' and clearly states the condition: when a user wants a project-opening plan from permit dependencies. It provides clear context but does not mention exclusions or alternatives.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the nuance that the checklist is a 'starter' (not exhaustive) and limited to 'a supported lane,' which is useful but limited. It does not describe return behavior or error cases, but the bar is lowered due to annotations.

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 a single sentence, front-loaded with the usage trigger. It is efficient with no wasted words, though it is arguably too sparse given the parameter ambiguities. Still, for what it attempts, it is concise and well-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?

With 2 parameters (neither required) and an output schema, the description is too minimal. It omits explanation of the 'text' parameter entirely and does not clarify what makes a lane 'supported.' While the output schema exists, the input side is under-specified, making the tool difficult to invoke correctly in all cases.

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 gives minimal meaning to 'lane' via 'supported lane' but does not explain valid values or behavior for unsupported lanes. The 'text' parameter is completely unexplained, leaving a significant gap for correct invocation.

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 a starter permit/opening checklist. It uses a specific verb ('generate') and resource ('permit/opening checklist'), and the phrase 'for a supported lane' adds scope. While it doesn't explicitly contrast with sibling tools, the distinct resource type differentiates it adequately.

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 begins with 'Use this when a user wants...', providing clear guidance on when to use the tool. It does not mention alternatives or exclusions (e.g., when to use build_inspection_questions instead), so it lacks the full when-not-to-use guidance that would earn a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe, side-effect-free operation. The description adds only the purpose (identifying forms) without additional behavioral context such as how parameters influence results or return structure. It 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.

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

The description is a single sentence, directly states the trigger condition, and contains no filler. It is efficiently structured and front-loaded with the usage scenario.

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

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

Despite having an output schema, the description lacks any information about the input parameters' meaning or expected values. For a tool with two unexplained parameters, the description is not complete enough to guide correct invocation. It only provides the usage scenario.

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

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

The input schema has two string parameters, lane and text, with no descriptions. The description does not mention these parameters at all, leaving them completely opaque. With 0% schema coverage, the description fails to compensate, making it difficult for an agent to know what values to 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 clearly states the tool identifies likely forms or approvals for a project, using the verb 'identify' and specifying the resource (forms/approvals) and context (project). This distinguishes it from sibling tools like build_inspection_questions and generate_permit_checklist, which focus on different aspects.

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 explicitly says 'Use this when a user wants likely forms or approvals identified for a project,' providing a clear usage condition. It doesn't explicitly mention alternatives or exclusions, but the condition effectively scopes it to form/approval identification.

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