CounselorAI

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds valuable behavior: it notes the tool is 'Free' (cost implication) and specifies the return value ('credits left'), which is absent from the schema (no output schema). It does not contradict annotations; it supplements them with cost and output semantics.

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 front-loads the key facts: 'Free', 'Returns credits', and usage timing. Every word carries value; there is no filler 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?

Given the tool's simplicity (no parameters), the readOnlyHint annotation, and the absence of an output schema, the description fully equips an agent: it explains what the tool returns, its cost, and when to call it. Nothing necessary for correct invocation is missing.

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?

There are 0 parameters, and schema coverage is 100% (trivially). With no parameters, the description need not explain any. The baseline for 0-param tools is 4, and the description correctly provides no spurious parameter details. It correctly implies the tool requires no 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 states a specific verb ('Returns') and a precise resource ('credits left on this API key'), making the tool's purpose unambiguous. It clearly distinguishes this from the sibling tools (aid, appeal, etc.), which serve different functions. No ambiguity exists.

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 provides when to use the tool: 'Call it before a long run of billed calls.' This gives clear context for invocation. While it doesn't mention alternatives, none are needed since this is a distinct utility, and the guidance is actionable.

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 useful behavioral detail beyond the annotations: the call costs about 73 credits, and the output itself includes a statement that it is not an official determination. The annotation flags are not very informative, so this extra context carries real weight.

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 compact and well structured: the first sentence states the core purpose, the second adds the key limitation and output behavior, and the cost line is a relevant operational detail. No filler or repetition.

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 text-generation tool with no output schema, the description sufficiently conveys the audience, output style, non-official status, and cost. It could be stronger on output structure or explicit sibling routing, but the essential calling context is 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?

Schema coverage is 100%, so all seven parameters are already documented in the input schema. The description does not add much parameter-level meaning, but it does provide the general context that these inputs describe the family and schools being compared. Baseline 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 states a specific purpose: explain expected aid across a list of schools in plain language for a counselor to walk a family through. The 'never an official determination' qualifier adds useful precision, though it does not explicitly differentiate from sibling tools.

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 gives clear context for use: this is a walkthrough explanation for counselors, and it explicitly rules out use as an official determination. It does not name sibling alternatives or state conditions for choosing a different tool, but the intended use is well established.

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 only indicate non-read-only and non-destructive, which is minimal. The description goes far beyond by disclosing cost ('about 353 credits (~$0.353) per call'), speed ('slowest, typically 30 to 60 seconds'), and internal process ('Runs a 5-step drafting pipeline'). It also clarifies the output nature (the letter itself, not advice). This is rich behavioral context that annotations do not cover.

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 compact yet information-dense: a one-line purpose, a condition clause, an output clarification, a process note, and a cost line — all in a few sentences. It front-loads the primary purpose and then covers essential operational details without fluff. 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 drafting tool with 11 parameters (all well-described in the schema) and an output schema absent, the description covers the key contextual needs: what it generates, when to invoke it, cost, speed, and output tone. It does not need to repeat parameter semantics. The description is complete enough for an agent to call it correctly and anticipate consequences.

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 100%, meaning every parameter already has a detailed explanation (e.g., appealType enum semantics, status categories, naturalness scale). The tool description adds no additional parameter-specific guidance beyond what the schema 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.

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

The description opens with a specific verb and resource ('Draft a financial aid appeal letter to a college financial aid office'), immediately clarifying what the tool does. It also provides concrete trigger examples (income dropped, expense appeared, competing offer, FAFSA error) that distinguish it from analysis or advisory tools, making its purpose unmistakable.

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 instructs when to call it ('Call this when a family needs to ask for a review of an award') with specific scenarios, and it states a clear exclusion ('Returns the letter, not advice on whether to appeal'). It does not explicitly name alternative sibling tools (like letterlens) for when not to use it, but the given triggers and output clarify the appropriate context well enough.

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 readOnlyHint, the description reveals several non-obvious behaviors: it classifies aid types, computes real out-of-pocket cost, finds buried renewal conditions, flags Professional Judgment openings, and compares letters when multiple are provided. It also discloses the credit cost, which annotations cannot convey. There is 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.

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

The description is front-loaded with the core purpose, then enumerates key behaviors in short clauses, closes with read-only and cost information. Every sentence adds useful information, and there is no filler or repetition of schema fields.

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?

There is no output schema, so the description carries the burden of explaining what the agent should expect back. It enumerates the analytical outputs clearly and adds practical context like cost and comparison behavior. Combined with the fully described input schema, this is complete enough for an agent to use and invoke confidently.

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 100%, so the baseline is 3. The description adds little parameter-level meaning beyond the schema; the main addition is the general 'one to three letters' framing. The schema already explains letter contents, studentName, and scorecardData clearly.

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 names a specific verb ('Break down') and a specific resource ('financial aid award letters'), then details the exact outputs: grants, loans, work-study, out-of-pocket cost, renewal conditions, and Professional Judgment appeal flags. This is clearly differentiated from the broader sibling tools like letterlens by its financial-aid-specific scope.

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 clear context: it handles one to three award letters, compares multiple letters side by side, and can take optional scorecard data for grounding. It does not explicitly name alternatives or say when not to use it, 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.

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

Annotations provide only generic hints (readOnlyHint=false, destructiveHint=false), so the description carries some behavioral burden. It adds that the output is a process checklist rather than an award computation, and includes a concrete cost note; it does not disclose side effects, persistence, or rate limits, but for a checklist generator the non-goal plus cost is reasonable context.

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 plus a cost line; the main verb and scope appear immediately, followed by value and a non-goal. No filler, and each clause adds information an agent or user would want.

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 eight optional parameters and no output schema, the description gives enough orientation: it names the core drivers, clarifies the deliverable, and states a boundary. It doesn't describe output shape or all optional inputs, but the schema covers parameters and a checklist's format is self-evident, so this is adequate though not exhaustive.

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 100%, so baseline is 3. The description calls out grade, dependency, and income as drivers, reinforcing the schema but adding no new meaning about formats, defaults, or interactions; the schema already documents all eight 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?

States a specific action ('Produce a FAFSA action checklist') with clear scope ('for one student') and key inputs (grade, dependency status, income band). The closing 'Does not compute an award' distinguishes it from award/aid siblings without naming them.

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?

Clear context is given: it answers the process question ('what do we do, in what order, by when') rather than calculating awards. It gives an implicit exclusion ('Does not compute an award'), but it does not name sibling tools or state explicit when-to-use/alternative conditions.

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 discloses meaningful behavioral traits beyond annotations: it preserves quoted text, checks the result against the source, does not invent a voice, and does not claim to evade AI detectors. These are important non-obvious behaviors that help an agent set expectations correctly.

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 front-loaded with the core purpose, followed by usage guidance, behavioral constraints, and an explicit exclusion list. Every sentence adds useful information, and the cost note is clearly separated.

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 what the tool does, when to use it, what it preserves, and what it does not promise. The absence of an output schema is not a major gap because the expected result is implied by the rewrite task, though a brief note on return format would make it fully 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 description coverage is 100%, so the input schema already documents all parameters well. The description does not add parameter-specific details beyond the schema, which aligns with the baseline of 3 for high schema coverage.

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 a specific verb ('rewrite'), a clear resource ('reader-facing prose'), and the transformation goals ('direct, specific, personal') without changing facts. It also differentiates from other tools by explicitly excluding code, SQL, JSON, legal text, and technical specs.

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?

Provides explicit use cases ('outreach, emails, letters, posts, and narrative copy') and explicit negative guidance ('Do not use it for code, SQL, JSON, legal text, or technical specifications'). This gives the agent clear conditions for when to select this tool over others.

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 destructiveHint=false, and the description reinforces this with 'Read-only' while adding useful cost context ('about 93 credits ~$0.093 per call'). It also clarifies the tool only critiques and does not rewrite, which is meaningful beyond the schema and annotations. It does not disclose the exact output structure, but the annotation safety profile lowers the burden.

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 compact and front-loaded: the first sentence states what it does and what it returns, the second prevents misuse, and the cost line is a genuinely useful decision signal. Every sentence earns its place with no filler or repetition of the schema.

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 review tool with no output schema, the description gives enough context to select and invoke it correctly: expected input type, return categories, non-rewriting behavior, the sibling to use for fixes, and cost. An agent would understand what this tool is for and how it differs from siblings like revision and humanize.

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 100%, so the schema already explains letterText, focus, and purpose. The description adds no parameter-specific syntax or formatting details beyond what the schema provides. The baseline of 3 applies because the schema carries the burden adequately.

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 names a specific verb ('Analyze') and resource ('finished recommendation letter') and states the tool's output with concrete categories: vague, asserted without evidence, generated. It also distinguishes itself from rewriting via 'not to rewrite one' and points to 'revision' as the sibling that applies fixes.

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 when to use it ('critique a draft') and when not to ('not to rewrite one'), and names the alternative tool to use for applying fixes ('use revision'). It also adds an economic signal ('far cheaper than drafting'), which helps the agent choose appropriately.

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 are sparse, so the description carries some burden for behavioral context. It usefully discloses cost and downstream value, but it does not clarify whether a profile is persisted, what side effects exist, or the exact structure of the returned profile. There is no contradiction with 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.

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

The description is tight and front-loaded: purpose first, then usage guidance, then cost. Every sentence earns its place and no information is repeated from the schema.

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 tool with 11 optional parameters and no output schema, the description provides purpose, usage timing, cost, and downstream consumers of the output. It stops short of describing the output shape in detail, but the references to relationship, traits, story, and keyDetails give an agent enough mental model to call 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?

Six of eleven parameters have schema descriptions (55% coverage), and the remaining parameter names like goals, grade, major, school, and activities are fairly self-explanatory. The description itself adds little per-parameter detail, but it does explain how the output feeds rec and appeal fields, which indirectly clarifies the purpose of the inputs.

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 action and result: 'Turn raw counselor notes into a structured student profile.' It also distinguishes the tool from siblings by positioning it as the cheap first step whose output feeds rec and appeal fields, so an agent can clearly tell it apart from tools like rec or appeal.

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 an explicit trigger: 'Run this first when working one student across several tools' and adds cost information to support the decision. It does not explicitly say when not to use it or name a direct alternative, but the downstream references to rec and appeal provide enough routing 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?

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: the call is free, it validates input, and it returns a credit hold estimate plus coverage check. This goes beyond the annotation without contradicting it.

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 tight sentences, front-loaded with the key fact that the tool is free. Every sentence contributes actionable information about what the tool does and when to use it.

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 no output schema, the description adequately explains the return value: exact credit hold, price basis, and balance coverage. It also communicates the validation behavior and free nature, making it complete for a simple two-parameter quote 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?

Schema description coverage is 100%, with both 'tool' and 'input' documented in the schema. The description reinforces that input is 'the input you intend to send' and that omission gives a default estimate, but it does not add substantial meaning beyond 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 the tool validates input for a tool and returns the exact credit hold a real call would take, plus balance coverage. It uses a specific verb ('quote', 'validates', 'returns') and distinguishes itself from paying/executing the call by emphasizing it is free and for budgeting.

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 to use it to budget before a billed call or to lint an input for free, providing clear usage context. It does not explicitly name alternatives, but the use cases are concrete enough for an agent to know 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.

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

The annotations provide only generic non-destructive flags, so the description carries the behavioral burden. It discloses cost explicitly, notes the shared 5-step pipeline with appeal, and frames the tool as drafting rather than signing. It does not describe output details, but the generative/drafting nature is adequately conveyed.

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 four short sentences with no filler: purpose, write-vs-critique routing, pipeline context, and cost. The most important distinction is front-loaded, and 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 14-parameter generative tool with no output schema, the description covers the essential decision, cost, and pipeline context, while the schema handles input details. A sentence about the returned artifact being the drafted letter would increase completeness, but it is strongly implied by 'Draft a letter' and the write/critique contrast.

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 93%, so the baseline is 3. The description itself adds no parameter-level detail, but the schema's rich per-field notes—story as the 'single highest-value field', traits needing prose, profType only for professional purposes—cover the parameter semantics effectively.

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 and resource: 'Draft a letter of recommendation from counselor notes.' It reinforces the action with 'Call this to WRITE a letter,' clearly separating it from critique and making the tool's core purpose unmistakable.

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 gives explicit when-to-use guidance ('Call this to WRITE a letter') and when-not-to-use guidance ('To critique one that already exists, call letterlens instead'), including the cost rationale ('much cheaper'). This is an exemplary routing statement.

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 (readOnlyHint=false, destructiveHint=false) convey little, so the description carries the burden. It adds meaningful behavioral detail: returns revised text, changes only what the instruction requests, and costs about 97 credits per call. No side effects are disclosed, but the wording implies a contained transformation.

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 compact and front-loaded: it states the primary action first, then adds pairing guidance, scope constraints, and cost. Every sentence earns its place with no filler or repetition.

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 two-parameter tool with no output schema and minimal annotations, the description is complete enough. It explains what the tool does, what it returns, how it pairs with a sibling tool, what its behavioral scope is, and the cost. No critical operational detail is missing.

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 100%, so the schema already fully documents both parameters. The description adds only the workflow-level notion of applying 'one instruction,' which is also present in the instruction parameter description. This is the baseline score for schema-covered 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 states a specific action ('Apply one instruction to an existing letter') and a specific deliverable ('return the revised text'). The additional scope constraint ('Changes only what the instruction asks for') makes it clear what this tool does and distinguishes it from broader editing tools.

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 positions this tool in a workflow: 'Pair it with letterlens: review to find the problems, revise to fix them.' This gives clear usage context. It does not enumerate exclusions relative to all siblings, but the pairing guidance is strong enough.

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 discloses key behavioral traits beyond the sparse annotations: it runs a live web search, has higher latency and cost, and returns a verification warning because scholarship programs change. It also positions the output as a research starting point, which sets accurate expectations about reliability. The annotations provide little behavioral coverage, so this description carries the burden well.

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 compact: two substantive sentences plus a cost line. The main purpose is front-loaded, followed by necessary caveats and operational cost. No filler or redundant restatement of the tool name.

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 live-search tool with no output schema, the description covers the key decision factors: what it returns, why it's slower and pricier, and how trustworthy the output is. The main gap is that, with zero required parameters, it doesn't state what minimal inputs are needed or how the output is structured beyond 'scholarships and application angle.'

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 88%, so the structured schema already documents most parameters and even adds strategic context such as 'departmental awards are usually the least contested.' The description itself does not elaborate on parameters, but the schema compensates adequately, leaving this at the baseline.

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 concrete action: 'Surface scholarships worth this student's time and the angle their application should take for each.' This clearly defines the output and intent. It distinguishes itself from generic matching by mentioning live web search and 'other analysis tools,' but it does not name specific sibling tools, so sibling differentiation is incomplete.

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 warns that the tool is slower and more expensive than other analysis tools and frames the result as a research starting point, giving the agent a clear sense of when to use it. However, it does not name alternative tools or explicitly state when not to use this tool.

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 readOnlyHint and destructiveHint annotations, the description discloses the per-call cost (about 173 credits) and the deliberate policy of keeping financial aid terms untranslated. It also states 'Read-only' in prose and explains the family-facing rationale behind the terminology behavior.

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 front-load the purpose and key behavioral constraints, with the cost line separated for scannability. There is no filler or unnecessary repetition.

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 two-parameter translate tool with complete schema coverage and read-only annotations, the description supplies the essential context: input origin, target audience, terminology policy, and cost. It does not explicitly describe the return value, but that is strongly implied by the tool's name and purpose, so there is no meaningful invocation gap.

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 100%, so the schema already fully documents sourceText and targetLang; the description does not need to add parameter-level detail. It adds light semantic framing by describing sourceText as counselor-facing output, but no new syntax or format information.

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 and resource: 'Translate counselor-facing output into a family's language.' It further clarifies scope by explaining that FAFSA, Pell, SAI, COA, and loan names intentionally stay untranslated, which distinguishes this behavior from generic translation tools.

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 clearly establishes when to use the tool: when converting counselor-facing text into a family's language, with the schema adding that sourceText is usually another tool's output. It does not explicitly name alternatives or state when not to use it, but the use case is specific enough to guide selection.

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