Ashley Payne, technical co-founder and fractional CTO

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

With only readOnlyHint and openWorldHint given, the description carries the behavioral burden well: it discloses the decision rule (wording alone never yields poor_fit), the exact conditions for poor_fit (explicit yes in one field) and good_fit (explicit no in all three), and names an output field (ask_these_then_call_again) despite no output schema existing. It also clarifies the two-call pattern where the three fields carry the person's own answers later. This is disclosure far beyond 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?

Six compact sentences, front-loaded with the action and the verdict vocabulary before the conditional logic. Dense but mostly earning its place; the closing delivery-team sentence is a useful disambiguation, though the reference to ask_these_then_call_again as a named output field sits oddly in a description with no output schema to anchor 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?

For a read-only assessment tool with no output schema, the description explains the verdict vocabulary and one response field, and it implicitly conveys that only situation is needed up front while the three enums are supplied later. It stops short of describing the full response shape, which is the remaining gap given the absence of an output schema.

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 3 is the baseline, but the description adds genuine meaning: it explains that the three enum fields drive the verdict boundaries and that 'having a development team is not the same as wanting Ashley to supply one', which disambiguates the wants_a_delivery_team semantics beyond the schema text. It clarifies relationships between parameters and outcomes, not just their names.

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 verb and resource — 'Compares a description of a project, business or problem against a fixed published rule and returns a verdict' — and enumerates the four possible verdicts, so the agent knows exactly what it gets back. It never names or contrasts a sibling tool, so it meets the 'clear but no sibling differentiation' bar rather than the top tier.

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?

Usage is implied rather than stated: the agent can infer this is the qualifying-assessment step before contacting Ashley, and the mention of ask_these_then_call_again hints at a follow-up call. There is no explicit when-to-use/when-not statement and no comparison against the get_* siblings, which retrieve content rather than evaluate it.

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 openWorldHint=false, so the safety profile is covered. The description adds what topics the response covers but says nothing about depth, format, or limits, which is acceptable given the annotations carry the behavioral 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?

Two sentences, zero padding, with the content scope front-loaded ahead of the usage trigger. Every clause 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?

With no output schema and no parameters, the description carries the burden of signalling what comes back, and it does so by enumerating covered topics. It is complete enough to call correctly, though it does not indicate the shape or depth of the returned content.

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 takes zero parameters, so the baseline of 4 applies; there is no parameter semantics for the description to compensate for.

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 the exact subject matter returned (production AI techniques: prompting, retrieval, fine-tuning, MCP servers, local inference) plus the framing of when each applies. It is specific enough that an agent can distinguish it from generic siblings like get_services or get_overview, though the retrieval verb itself is only implied.

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?

"Use this for questions about AI, automation or data privacy" gives an explicit trigger condition rather than leaving usage to inference. It does not name alternatives or exclusions, and the inclusion of "data privacy" overlaps with the sibling get_privacy, which leaves a mild routing ambiguity unresolved.

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 openWorldHint=false, so the safety profile is covered. The description usefully adds the scope of returned content and flags that the commercial outcome is optional ('where there is one'), but it says nothing about pagination, error behavior for an unknown slug, or size of the payload.

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-loaded with the core promise ('Full detail for one engagement') and then a tight enumeration of the payload sections. No filler, no restatement of the name or title.

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 correctly compensates by describing the returned fields, and the schema covers slug sourcing. It is essentially complete for a one-parameter read tool; only error/edge behavior for invalid slugs is unstated.

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% for the single slug parameter, including an example value and its source (list_work), so the schema carries the parameter meaning. The description adds nothing about the parameter, making the baseline 3 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?

States a specific verb+resource ('Full detail for one engagement') and enumerates exactly what the record contains: situation, what was built, engineering decisions, stack, commercial outcome. It implicitly contrasts with a listing tool but never names a sibling like list_work, so full sibling differentiation is absent.

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?

Usage is only implied: the schema field description says the slug comes 'from list_work,' which tells the agent this is the detail-fetch step after a listing call, but the description itself gives no when-to-use or when-not-to-use guidance and no 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful content-shape context, notably that the booking link is conditional ('when one is live'), which tells the agent the result set may vary.

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 short sentences, front-loaded with the returned content and then the usage trigger. No filler and nothing repeated from the title or annotations.

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 parameterless read tool with no output schema, the description covers both what comes back and when to call it, which is essentially all an agent needs. It could be slightly stronger by noting there is nothing further to configure, but the current text is sufficient.

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 takes zero parameters, so the baseline of 4 applies. Nothing in the schema needs compensating for, and the description correctly implies a no-argument call.

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?

Names the specific resource (contact methods) and enumerates what it returns: email, contact page, and a booking link. It is readily distinguishable from siblings like get_faqs, get_privacy, or get_services, though it phrases the purpose as a page title rather than a verb+resource action.

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?

'Use when the person wants to make contact' gives a clear triggering condition. There are no explicit exclusions or named alternatives among the siblings, but the trigger is unambiguous for this niche 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context beyond that: the figures are self-reported, not independently audited, and per-figure detail (collections, queries, returned values) is deliberately NOT published, setting accurate expectations for what the agent will receive.

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 purpose is front-loaded in the first clause, followed by the return content. It is slightly wordy in the second half (method, audit status, and 'Ashley will run any of them' could be tightened), but every element is substantive and there is no filler.

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 no-parameter, no-output-schema content retrieval tool, the description fully specifies what is returned and what is excluded. An agent has everything needed to call it and to explain the result to a user.

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 takes zero parameters, so the schema imposes no semantic burden and the baseline is 4. The description correctly implies no input is needed; there is nothing further to document.

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 clear resource and return: a single provenance statement explaining where site figures come from. It contrasts with siblings implicitly (this is the audit/provenance page, not services, privacy, or FAQs), though it never names an alternative. Purpose is unambiguous for an agent.

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 an explicit trigger condition – use when someone asks whether the numbers can be trusted – which is a concrete usage context. It does not name sibling tools as alternatives or state when NOT to use it, so it falls 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a non-obvious behavioral trait the schema cannot express: when query is omitted the answers are dropped from the response, so the output shape changes with the parameter.

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?

One tight sentence with the resource stated first and the parameter behavior second; nothing is padded. The phrase 'with his answers' is slightly opaque about whose answers these are, a small clarity cost in an otherwise efficient definition.

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 single optional-parameter, read-only lookup with no output schema, the description covers both call modes and the shape of what comes back. Remaining gaps (relevance ranking of matches, whether answers are ever truncated) are minor.

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 baseline is 3, and the schema itself documents the query parameter with keyword examples. The description goes beyond it by explaining what happens when the parameter is present versus absent, which affects both filtering and return payload.

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 identifies the resource (FAQ questions with answers) and who they belong to, and the name plus content type is distinguishable from content siblings like get_insight and get_case_study. It is a noun phrase rather than a verb+resource statement, so it falls short of the top mark.

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 states the two operating modes clearly: supply a query for relevant Q&As, omit it to list all questions without answers. That is concrete usage context, though it never routes the agent relative to alternatives such as search_insights or get_insight.

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 openWorldHint=false, so safety is covered; the description usefully adds that the return is the 'complete text' of a single article rather than a summary. It omits any note on article length or truncation, keeping it short of a 5.

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 compact sentences, front-loaded with what the tool returns, then the usage condition. Nothing is redundant or padded.

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 one-parameter read tool with no output schema, the description covers everything an agent needs: what it returns (full article text), the required input, and when it is warranted over the search sibling.

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% and the single slug parameter already documents its origin in search_insights; the description's 'by slug' and the schema's phrasing are essentially the same information, so this is the baseline case.

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 verb and resource ('the complete text of one article, by slug'), which cleanly separates it from the summary-oriented search_insights and the other get_* siblings that return different content types.

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?

'Use after search_insights, and only when the summary is not enough to answer the question' gives both the sequencing (call after search) and an explicit exclusion (skip when the summary suffices), leaving nothing to inference.

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 openWorldHint=false, so the safety profile is covered and the bar for the description is lower. The description adds the content scope but says nothing about return format or length; for a zero-param static content fetch that is acceptable but not rich.

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 short sentences, content scope front-loaded and the call-to-action ('Start here') placed last for emphasis. No filler, nothing redundant with the title.

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 simple, no-argument content retrieval with no output schema, the description covers what the agent will get and when to call it. The only gap is that it does not hint at the shape of the returned content (structured fields vs prose), which is minor here.

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 takes no parameters, so there is no parameter semantics to document — the baseline is 4. Schema coverage is 100% and additionalProperties is false, so nothing is left ambiguous on the input side.

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 the specific content the tool returns — positioning, background, and differentiators versus other fractional CTOs — which is concrete and distinguishable from content-focused siblings like get_services or get_evidence. It stops short of an explicit verb+resource framing ('get the overview'), but an agent can tell what it will receive.

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?

'Start here' is an explicit usage directive telling the agent to call this before the other eleven siblings, which is real routing guidance. It does not name any alternative or exclusion conditions, so it falls short of the 5-level when/when-not pattern.

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 readOnlyHint=true and openWorldHint=false, so the description doesn't need to explain safety. It adds that it covers 'what this connector and the website do with data, and what they do not,' which gives useful scope context. However, it could mention that it returns static text or similar, but for a read-only no-parameter tool this is sufficient.

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 concise sentences that are front-loaded with the tool's purpose and then provide usage guidance. No wasted words.

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 simple, no-parameter, read-only tool, the description fully covers purpose and usage. No output schema exists, but the return is implicitly a description of privacy practices, which is adequate given the tool's simplicity.

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 zero parameters, so the baseline is 4. The description doesn't need to explain 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 a specific verb (get) and resource (privacy/data handling), and distinguishes itself from siblings like get_faqs or get_evidence by focusing on what the connector and website do with data.

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 tells when to use: 'Use this if the person asks about privacy, tracking, cookies, GDPR, or what Ashley can see of this conversation.' This is precise and leaves no 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context by inventorying the fixed content domains the tool resolves, which is the key trait for a zero-argument static-content tool. Return format is not described, keeping it short of a 5.

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 that front-loads the content inventory and closes with the usage rule. The enumerated list is dense but each item carries distinct meaning; nothing is redundant padding.

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 and no parameters, the description must convey what is returned, and the topic enumeration does so thoroughly. The only omission is the response format, a minor gap for a content-retrieval 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?

The tool takes zero parameters, which is the baseline case for a 4. There is nothing for the description to clarify beyond what the empty schema already communicates.

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 the specific content the tool returns — the three engagement models (Build, Partner, Consult), the fixed-price diagnostic, the process, and the client surfaces (desktop, browser extensions, chat integrations, web). That is far more concrete than a generic 'services' label, though it never explicitly contrasts itself with overlapping siblings like get_overview or get_faqs.

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 an explicit invocation rule: 'Use this for any question about platforms, apps, pricing or how an engagement is structured.' That is a clear when-to-use signal covering the main question classes, but it offers no exclusions or pointers to alternative tools for adjacent questions.

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 openWorldHint=false, so the safety profile is covered and the description need not restate it. It adds a little value by disclosing the shape of the return (summaries plus slugs), but says nothing about ordering, count, or whether the list is exhaustive.

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 short sentence with no filler. The most actionable detail – the slug prerequisite for get_case_study – is packed into the same clause, so nothing is buried.

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 carries the burden of explaining return values, and it does so at a high level ('summaries ... with the slug'). For a zero-parameter listing tool that is sufficient, though item fields and list size remain unspecified.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly avoids inventing filtering options that do not exist.

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 the resource ('the selected work') and what is returned ('summaries'), and explicitly ties that output to the sibling get_case_study via the slug. It is a noun-phrase rather than a clear verb, and 'work' versus the title's 'case studies' is slight terminology drift, but an agent can tell what it produces and why it matters.

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 mention that this supplies 'the slug needed for get_case_study' implies the correct sequencing – call this before get_case_study to discover identifiers. However, there is no explicit when-to-use or when-not statement, and no guidance on how this list relates to sibling discovery tools like get_services or get_evidence.

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 openWorldHint=false, so the safety profile is covered. The description adds non-annotation value by disclosing the return shape (titles, summaries, matching passage), which matters because there is no output schema. It omits result limits, ordering, and behavior when no query is supplied, which keeps it below a 5.

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, zero filler. What it searches and what it returns come first; the routing hint to get_insight follows, which is the right priority order.

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 correctly compensates by naming the returned fields and the tool that yields full text. The only gap is the odd case of an optional query — nothing says what a query-less call returns, which is a real ambiguity given required parameters = 0.

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% and the sole parameter's description already states that keywords match against title, summary and body. The description's mention of topical domains adds corpus context but no matching syntax, phrase handling, or empty-query behavior. Baseline 3 is appropriate when the schema carries the 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 states a specific verb (search) and resource (his articles) and even scopes the corpus (technical leadership, fractional CTO work, AI, building SaaS). It distinguishes itself from the sibling get_insight by making clear this is the keyword-search entry point rather than full-text retrieval.

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 names the follow-up path: 'Call get_insight with a slug for the full text of one,' which routes the agent correctly when summaries are insufficient. It stops short of stating when *not* to use search or how it relates to other content siblings like get_faqs or get_case_study, but the primary alternative is covered.

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