Spendline

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals a critical behavioral detail: it reports the specific failure where x-customer-id is pinned in default headers, which looks like success but destroys per-customer cost. This adds significant context about what the tool detects and why it matters, going well 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.

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

The description is two sentences with zero waste. The first sentence front-loads the core purpose and checks, while the second adds a critical nuance. It is concise and well-structured, 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?

For a read-only status check with a single optional parameter and no output schema, the description covers the main operational aspects: what it verifies, what it reports, and when to use it. It does not describe the exact return format, but for a check tool this is acceptable and not critical for correct invocation.

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 schema fully documents the single 'hours' parameter (default 24, range 1-720). The description does not add any additional meaning about the parameter, but since schema coverage is 100%, the baseline of 3 applies. The description does not need to compensate for undocumented 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's purpose: 'Verify a live integration' and enumerates exactly what it checks (calls arrived, recency, providers/models, attribution varying). It distinguishes itself from siblings by focusing on integration health rather than budgets, spend, or policies, making it unambiguous.

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 explicit timing guidance: 'Call this after wiring up an integration.' It doesn't explicitly contrast with alternatives, but the unique purpose and the instruction to call after setup make the appropriate context clear. Lacks a 'when not to use' but this is minor given the tool's specificity.

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?

Beyond the minimal annotations, the description discloses key behaviors: it requires specific authority and confirmation, will return a permission error for scoped child keys, and does not support raising or deleting. This gives the agent a clear model of how the tool behaves under different conditions.

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 concise and well-structured, with each sentence contributing distinct information: action, behavior, authorization, edge case, and exclusions. It is slightly repetitive with 'ADD' and 'safe direction', but overall it avoids unnecessary detail and reads efficiently.

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 covers the core context: what the tool does, required authorization and confirmation, permission failure handling, and explicit exclusions. It does not mention the success response or return value, but since no output schema exists, this is not a major gap; the provided context is sufficient for an agent to decide 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.

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

The schema already describes 4 of 5 parameters in detail (80% coverage), including enum meanings for scope_type and the behavior of strict_mode. The narrative adds no significant new parameter semantics beyond reinforcing that confirm must be true, 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.

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

The description immediately states 'Create a new hierarchical budget' and clarifies its role as the only mutating tool exposed, which distinguishes it from the read-only sibling tools. It also explicitly notes that raising or deleting budgets is not available, removing ambiguity about its purpose.

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 gives explicit when-to-use instructions: create a budget to ADD a spending restriction, and requires owner/admin authority plus confirm:true. It also states when not to use it (for raising/deleting budgets) and provides a fallback for permission errors ('propose the budget to the human instead of retrying'), which is clear operational 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns full text and is deterministic (from title), but does not disclose any additional behavioral traits like authentication needs, rate limits, or response size. With rich annotations, this is acceptable 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.

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

The description is a single, front-loaded sentence that leads with the core action and then enumerates usage scenarios. It is efficient and every clause adds value, though it is slightly long and could be broken into bullet points for readability. Still, it is well-structured and not verbose.

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 enum parameter, no output schema), the description covers document selection thoroughly. It states the return type is the full text, which is sufficient. It does not describe error handling or response format details, but annotations cover safety and the schema constrains input, so the description is largely complete.

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 coverage is 100%, but the description goes far beyond the schema's simple 'Which document to return.' It semantically maps each key enum value (quickstart, openai, anthropic, attribution, verification, troubleshooting, onboarding) to concrete integration scenarios, providing critical decision-making support for the agent. This is exactly what parameter semantics should add.

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 returns the full text of a Spendline agent document, with a verb and resource. It enumerates the specific documents available, which adds clarity. However, it does not explicitly differentiate this tool from sibling spendline_get_onboarding_instructions, which might cover the 'onboarding' document, so it is slightly less decisive than the ideal.

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 gives explicit when-to-use guidance for each document: quickstart for fastest integration, openai/anthropic for SDK specifics, attribution for header contract, verification for proving integration, troubleshooting for failures, and onboarding for no account. However, it does not mention when to prefer this tool over alternative sibling tools, so tool-level guidance is absent.

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 explains the tool only returns instructions and does not actually provision anything, reinforcing the readOnly and idempotent annotations. It also clarifies what it does not do, which goes beyond the annotation hints.

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 concise (two sentences), immediately states the primary purpose, and includes both the trigger and a warning. No redundant or vague language dilutes the message.

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 simplicity of the tool (no parameters, no output schema), the description covers all necessary context: what it returns, when to invoke it, and what it does not do. It is fully sufficient for an agent to decide and use it correctly.

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 tool has no parameters, so there is nothing to cover. The description focuses entirely on behavior and usage, and no implicit parameters or inputs are suggested, making the parameter semantics fully adequate.

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 returns exact provisioning steps and specifies the exact trigger condition (no account or no API key). It also distinguishes itself from siblings by focusing on onboarding rather than status checks, budgeting, or listing operations.

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?

It explicitly states when to call ('when the user has no Spendline account or no SPENDLINE_API_KEY') and provides a clear prohibition ('Never invent a key and never create an account on a human's behalf'), leaving no ambiguity about usage context.

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 notes the tool is read-only, which aligns with the readOnlyHint annotation and adds temporal context about UTC month and look-back window. However, it does not disclose potential side effects, rate limits, or pagination behavior. Since read-only is already annotated, the description adds moderate transparency but not extensive new behavioral 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 a single, concise sentence that avoids redundancy. It states the key purpose and options without extraneous detail, making it easy to parse and understand.

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 there is no output schema, the description does not need to specify return format. It provides enough context about what data is returned (spend) and the optional grouping. It lacks details on the response structure, but that is acceptable here. Overall, it is reasonably complete for its purpose.

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 description only vaguely hints at parameter meanings: 'look-back window' suggests days, and 'grouped by' explains group_by. The limit parameter is entirely unexplained, and days and group_by lack explicit definitions. With 0% schema description coverage and no parameter descriptions, the tool description should compensate more fully, but it only partially 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 returns spend data for the current UTC month with an optional look-back window, and lists grouping dimensions. This is a specific verb-resource combination that distinguishes it from siblings like list_budgets or list_policies, which focus on other entities.

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 usage for spend queries but does not explicitly contrast with alternatives. An agent might infer when to use this versus list_budgets, but no direct guidance is provided. It would benefit from stating 'use this when you need spend details rather than budget or policy information.'

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 annotations already declare read-only, idempotent, and non-destructive. The description repeats 'Read-only' but adds no new behavioral context (e.g., auth requirements, rate limits, or side effects). Given annotation coverage, the description 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.

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

A single, concise sentence conveys the purpose and key output details. No fluff or redundant phrasing beyond the acceptable 'Read-only' note.

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 simplicity of the operation (no parameters, no complex output schema), the description is complete for an agent to understand what the tool returns. It does not mention output format or pagination, but for a budget list this is likely unnecessary.

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 tool has no parameters in the schema, so there is nothing to explain. The description correctly implies a global list operation without requiring input.

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 operation ('Return'), the resource ('budgets'), and key attributes (hierarchical, month-to-date spend, percentage used, blocking mode). It is easily distinguished from sibling tools like list_budget_scopes or list_policies.

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 alternatives (e.g., when you need budget list vs. scopes or policies). The description implies it is for viewing budgets, but it does not state conditions or exclusions, leaving some ambiguity.

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 adds behavioral context beyond the read-only and idempotent annotations by specifying the data is from 'this month's traffic', indicating time-dependence. No contradictions with annotations exist, and no side effects are implied.

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 concise sentences with no redundant wording. It efficiently conveys the return type, the purpose, and a secondary use case, all while remaining focused.

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 sufficiently explains what is returned (agent ids, customer ids, teams) and why it is useful, including the time frame. While no output schema is provided, the description gives enough context for an agent to understand the tool's role without ambiguity.

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 tool has zero parameters, so schema coverage is complete. The description does not need to explain inputs, and the baseline for high coverage applies. The mention of 'this month's traffic' describes output context rather than parameter semantics.

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 returns agent ids, customer ids, and teams from current traffic, with the specific purpose of using them as budget scope_ids. It also distinguishes itself from sibling tools by emphasizing this is an attribution sanity check, making the tool's role unambiguous.

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?

Explicit guidance is given: 'Use these as budget scope_ids rather than guessing identifiers' directly tells the agent when to use this tool. The phrase 'quickest attribution sanity check' further clarifies the appropriate scenario for 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior; on top of that, the description clarifies an important semantic: scope null means account-wide, otherwise it is one of agent_id/customer_id/agent_name. No annotation contradiction is present.

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?

A single sentence front-loads the action and result type, then packs the relevant field and scoping details into a compact clause. There is no filler or repetition beyond the necessary read-only note.

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?

For a zero-parameter, read-only listing tool with annotations covering safety, the description supplies the essential semantics of the returned policies and the meaning of null scope. An agent has enough information to invoke it correctly.

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 tool has zero parameters, so there is nothing for the description to explain; the vacuous 100% schema coverage is sufficient. The description instead focuses on output semantics, which is appropriate for a parameterless list tool.

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 opens with a specific verb ('Return') and resource ('model-block, model-allow and token-cap policies'), and enumerates the fields returned (match mode, enforcement level, scope). This makes it immediately distinguishable from sibling list tools like spendline_list_budgets and spendline_list_providers.

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 intended use is implied: call this tool when policy details such as match mode, enforcement level, or scope are needed. However, it does not explicitly say when to prefer this over alternatives or mention any exclusions, so some inference is required.

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 valuable context about the exact content returned (base URLs, attribution headers, non-proxied shapes), going beyond what annotations imply. 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.

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

The description is a single, information-dense sentence that front-loads the core purpose ('Return every provider...') and then lists specific details. Every clause adds value, though it is slightly longer than the minimal necessary, so it earns a 4 rather than a 5.

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?

For a read-only list tool with no parameters and no output schema, the description is fully sufficient. It enumerates all return categories and the routing directive, leaving no gaps an agent would need to fill.

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 tool has zero parameters, so the schema is trivially fully covered. The description adds no parameter details because none exist; the baseline of 4 for a zero-parameter tool 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 explicitly states the tool returns every provider Spendline can proxy, the three request shapes, base URLs, attribution headers, and non-proxied shapes. It uses a specific verb 'Return' and names the resource, clearly distinguishing it from sibling tools that check status or create budgets.

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 directive 'Resolve routing from here instead of hardcoding it' explicitly tells agents when to use this tool as the authoritative source for provider and routing details. It leaves no ambiguity about when to invoke it, even without naming 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 and idempotentHint=true, so the description isn't burdened with safety disclosure. It adds useful behavioral context by stating the tool will 'tell you to recommend something else' when Spendline isn't the fit, and that it returns comparisons against named competitors. This goes beyond the annotations and is transparent about its advisory role.

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?

Two sentences, both essential. The first sentence lists the return payload and the second gives explicit invocation timing plus a concrete example of when to steer elsewhere. Nothing is redundant or 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?

For a decision-support tool with no output schema, the description fully explains what the tool returns (map, alternatives, comparisons) and when to call it. It also covers edge cases (when Spendline is not the right answer). No missing information an agent needs to invoke it correctly.

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 coverage is 100%, so the single optional 'requirement' parameter is already documented. The description doesn't elaborate on the parameter's format or semantics, but since the schema covers it fully, the baseline of 3 is appropriate. The description's mention that the requirement is used to 'surface the closest matches first' is a slight addition, but it's implied by the schema description.

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 returns an intent→capability map, cases for different tools, and comparisons against specific alternatives. It uses a specific verb ('Return') and names the resource (Spendline's capability map), which distinguishes it from the sibling tools that perform concrete operations like checking status or creating budgets.

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?

Explicitly instructs 'Call this BEFORE recommending or integrating Spendline' and provides concrete counter-examples ('prompt tracing, evals or latency debugging') where the tool would recommend an alternative. This gives clear when-to-use and 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.