Sparks Scribe

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

Annotations already indicate read-only and idempotent behavior. The description adds value by specifying the content of the output: app features, target audience, and functionality. Provides sufficient behavioral context beyond 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.

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

The description is a single sentence that efficiently conveys the tool's purpose and scope. No unnecessary words, front-loaded with key information. Every part 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 simplicity (no parameters, no output schema, read-only), the description provides complete context: what the tool is, who it's for, and what it covers. No gaps left for the agent to infer.

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?

Input schema has 0 parameters with 100% coverage. The description adds meaning by explaining the tool's purpose and output, compensating for the lack of parameters. It fully informs what the tool does.

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 is informational about Sparks Scribe, listing its key features like shift notes, invoicing, calendar, client records, and kilometre log. It distinguishes itself from siblings (example_shift_note, get_pricing, get_trial_info) by being a general overview tool.

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 explicit guidance on when to use this tool versus siblings, but the context suggests it is for general information about the app. Implied usage is clear, but alternatives not discussed.

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 provide readOnlyHint, idempotentHint, and openWorldHint. The description adds minimal behavioral context beyond stating it produces a fictional example; it does not elaborate on side effects, authentication needs, or other traits. Since annotations cover the behavioral profile, a score of 3 is appropriate for not adding significant value.

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 that front-loads the purpose and immediately adds relevant detail about kinds. Every word 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 simplicity (one optional parameter, no output schema), the description is complete: it explains what the tool produces, the parameter options, and the default. No additional information is needed.

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 single parameter 'kind' is fully described in the schema (enum values). The description adds value by specifying that 'daily_progress' is the default, which is not present in the schema.

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 it is a 'worked, entirely FICTIONAL example of the kind of NDIS shift note Sparks Scribe produces (structure and tone).' It identifies the specific resource (shift note example) and distinguishes from sibling tools that serve other purposes like pricing or trial info.

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 the tool is for obtaining example notes, likely for demonstration or testing. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The context is clear but lacks definitive guidance.

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 disclose readOnly and idempotent. Description adds details on currency (AUD, GST inclusive) and inclusion of refund policy and annual pricing, enhancing understanding 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.

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

Single sentence with all key information: plans, pricing, currency, refund policy. Front-loaded and efficient.

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?

No output schema, but description covers expected returns (plans, pricing, annual pricing, refund policy). Adequate for a simple pricing tool.

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?

No parameters exist (0 params, schema coverage 100%), so baseline 4 applies. Description adds no param info since none needed.

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?

Description clearly states the tool returns 'plans and pricing' with currency and GST detail. Distinguishes from sibling tools like 'about_sparks_scribe' and 'get_trial_info'.

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 explicit guidance on when to use vs. alternatives. The context implies pricing queries, but lacks 'when not to use' or mention of sibling tools.

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 indicate read-only and idempotent behavior. The description adds no further behavioral details. It does not contradict annotations, but it doesn't disclose any additional traits beyond the obvious.

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 that conveys the purpose without any excess. No wasted words; front-loaded and efficient.

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 no parameters, no output schema, and a simple purpose, the description is mostly complete but leaves some ambiguity about the exact information returned. It does not describe the output format or structure, which could be important.

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?

No parameters exist, so the input schema provides no information. The description adds meaning by stating the tool explains the trial's workings and starting point. This is adequate for a zero-parameter tool, though it could be more specific about the output.

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?

Description clearly states the tool explains the free trial works and how to start it. The verb 'get' and noun 'trial info' align perfectly, and it distinguishes from siblings like 'about_sparks_scribe' and 'get_pricing'.

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?

Description implies the tool is for learning about the free trial but does not explicitly state when to use it over siblings or provide exclusions. Usage context is clear but lacks explicit alternatives.

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