Kyle Romero (kgromero.com)

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuine behavioral context on top: the ordering guarantee (most recent first) and the fact that intra-company promotions are collapsed into a progression rather than listed as separate flat entries.

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 front-loaded sentence with no filler, and the parenthetical example is illustrative rather than redundant. Minor structural weakness: 'including promotions... and education' grammatically attaches education to 'Every title', which slightly muddies what the resource actually returns.

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?

Zero parameters, annotations present, and an output schema that carries the return shape — so the description only needs to convey scope and ordering, both of which it does. Nothing required to call this correctly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no filtering or arguments are needed to invoke it.

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 concrete resource and scope: every title held plus education, ordered most recent first, with promotion chains inside one company called out via a worked example (Manager → Senior Manager → Director at MEARS). That distinguishes it somewhat from get_experience, but it never names get_experience or get_education, so an agent must infer that this is the aggregated chronological view rather than the structured lists.

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 mention of education and cross-company progression hints this is the synthesized narrative view rather than a raw list, but there is no explicit 'use this instead of get_experience/get_education when...' guidance and no exclusions. An agent facing four overlapping siblings (get_contact, get_education, get_experience, list_experience) gets no routing rule.

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, idempotentHint, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful detail that a vCard link is included, but says nothing about authentication, whether the contact data can be absent, or pagination/link expiry, and output schema exists to cover return shape.

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 fragment with zero padding, and the enumerated profile types are front-loaded. It is telegraphic rather than a full sentence, but every element carries information.

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 tool with annotations and a full output schema, most of the burden is lifted, so the missing verb and missing sibling routing are the only real gaps. Still, without any statement of when to call this versus get_profile, the definition is only minimally 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 there is nothing for the description to disambiguate. Baseline 4 applies; the description cannot add parameter meaning that does 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 is a noun phrase that lists the returned content (contact details, LinkedIn, GitHub, Keyoxide profiles, vCard link) but never states a verb or explicitly says it retrieves the owner's contact information. It hints at a distinction from siblings like get_profile, but with a dozen sibling 'get_*' tools, the agent must infer that this is the contact-info endpoint rather than a general profile endpoint.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to any alternative tool. The closest sibling, get_profile, is never contrasted, so the agent has no rule for choosing between them.

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, idempotentHint, and closed-world scope, and an output schema describes the return shape, so the bar is lower. Still, the description adds nothing beyond them — nothing about what is returned when no education data exists, ordering, or completeness of the record.

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 words with zero padding, so there is no waste to trim. However, its brevity is under-specification rather than economy — nothing is front-loaded because nothing is stated beyond a fragment.

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 tool is trivially simple (no parameters, output schema present), so the missing return documentation is not a real gap. What is missing is sibling differentiation — an agent cannot tell from this description why it would call get_education rather than get_career_timeline or get_profile.

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 nothing for the description to clarify about inputs. The empty schema is self-explanatory.

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?

"Degrees and schools" is a noun fragment that largely restates what the name get_education already implies; there is no verb and no scope statement. It offers only marginal specificity (education = degrees + schools) and does nothing to separate it from siblings like get_profile or get_career_timeline, which plausibly overlap.

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?

There is no when-to-use guidance, no condition that selects this tool over get_profile, get_career_timeline, or get_experience, and no stated prerequisites. The agent must infer everything from the name alone.

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 that this is a read-only, idempotent, non-open-world lookup. Beyond that, the description adds useful behavioral context: it can retrieve one or more roles, matching is case-insensitive, and company or position name fragments are accepted.

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 short and front-loads the returned content before explaining the argument. The 'Args:' docstring formatting is slightly developer-centric but does not waste meaningful space.

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 one-parameter read tool with an output schema, the description covers the key lookup semantics and returned data categories. It does not explain ambiguous-match behavior or no-match behavior, but those gaps are modest given the tool's simplicity and the existence 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 description coverage is 0%, so the description must carry parameter meaning and it does: company_or_id accepts either an id from list_experience or a case-insensitive fragment of a company or position name, with concrete examples.

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 the resource (roles) and the kind of details returned (highlights, accomplishments, tech stack), which clearly distinguishes it from list_experience. However, 'Full details' is a somewhat generic verb phrase and the description does not explicitly contrast the tool with siblings like get_career_timeline.

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 implies usage by noting that the argument can be an id from list_experience or a company/position name fragment, which helps route the agent. But it does not explicitly say when to use this tool rather than list_experience or other sibling getters, nor when not to use 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, idempotentHint, and openWorldHint=false, so the safety profile is fully covered. The description adds only the content scope (interests, hobbies, tech news feeds) and says nothing about completeness, freshness, or whether the data is user-curated — a modest but real addition.

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 phrase with no filler, and the scope is front-loaded. It is a fragment rather than a sentence with a verb, which slightly undercuts clarity but wastes nothing.

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 an output schema present and zero arguments, the description needn't explain return values or parameters, and it doesn't. What remains missing is any disambiguation from the many sibling getters in this family, which is the one substantive gap for a simple read 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, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter information is missing or contradictory.

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 concrete resource set — personal interests, hobbies, and tech news sites Kyle reads — so an agent knows what content comes back. It does not, however, differentiate itself from near-neighbours like get_skills or list_side_projects, which could plausibly overlap with 'interests and hobbies'.

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?

There is no when-to-use guidance, no mention of when not to use it, and no pointer to an alternative sibling. The agent must infer that this is the tool for hobbies/interests purely from the noun phrase.

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 openWorldHint=false, so the safety profile is fully covered. The description adds the returned field set, which is mildly useful context but largely duplicates the output schema; it discloses nothing about scope limits, auth, or data freshness beyond that.

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 front-loaded sentence with the most important noun ('Overview') first and a compact field list; nothing is wasted and no padding is present.

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 parameters and an existing output schema, the description only needs to identify the tool and its scope, which it does. The one thing an agent might still want is an explicit pointer to the sibling tools for deeper fields, which is not provided.

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 no parameter semantics to explain and the baseline is 4. The description correctly does not invent parameter behavior.

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 resource (the profile of Kyle Romero) and enumerates exactly what the overview contains: title, summary, location, current role, total experience. That is clearly distinguishable from field-specific siblings like get_skills or get_education, though it never explicitly says 'use this for the overview, those for details.'

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 word 'Overview' implies this is the entry-point/aggregate call versus the granular siblings (get_contact, list_experience, get_skills), but the description never states when to prefer it or when to drill into a sibling. Usage is inferable but not articulated.

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, idempotentHint, and openWorldHint=false, so safety and repeatability are covered. The description does add real context beyond that by disclosing that skills are merged across roles and include where and how recently they were used, which tells the agent the data is pre-aggregated rather than raw. It says nothing about ordering, size, or whether the two views are returned in one payload or selected somehow.

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 lead sentence is front-loaded and tells the agent the two shapes of the result before any parameter detail. The Args block is compact and earns its space. The phrasing 'Kyle's skills two ways' is slightly informal but not wasteful.

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 an output schema present, the description needn't document return fields, and it correctly focuses on aggregation semantics and the one input. A single optional parameter and a three-line description are proportionate to the tool's complexity. The only missing piece is how the two views relate in the response.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single filter parameter, and it does so: case-insensitive substring, optional, with examples and the explicit note that it matches skill names, sub-components, and category names. That matching scope is genuinely new information not present in the schema. Minor gap is that the examples do not clarify whether multiple terms are OR'd or treated as one substring.

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 (skills) and states both views it returns: grouped by category and as technologies merged across roles. That is a specific verb-and-resource statement an agent can act on. It stops short of naming which sibling to use instead, but the sibling list covers different domains (experience, education, travel), so confusion is unlikely.

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 reader infers this is the tool for skill data and that the filter narrows results. There is no explicit statement of when to prefer this over get_experience or list_experience, even though those could plausibly surface overlapping technology data. No exclusions or prerequisites are given.

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, openWorldHint=false, and idempotentHint=true, so the safety profile is covered structurally. The description adds the data source and clarifies the lived_only filter, but it does not disclose return structure or pagination behavior; with an output schema present, that omission is acceptable but not fully informative.

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 short, front-loaded with the core purpose, and includes the parameter meaning in an Args block. It is efficient, though the Args formatting is slightly mechanical and the default behavior could have been stated more directly.

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 read-only tool with one optional boolean parameter and an output schema, the description provides enough context to invoke it correctly. It explains the source, the scope, and the filter, leaving only minor details such as explicit default behavior 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 0%, so the description must carry the meaning of the single parameter. It does so clearly: lived_only means only return places Kyle has lived, which distinguishes the filtered result from the default lived-and-traveled result. The default false behavior is implied rather than explicitly restated.

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 resource: places Kyle has lived and traveled to, sourced from the travel globe on kgromero.com. It distinguishes the tool from career, contact, education, and skills siblings by focusing on travel and residence history, though it does not explicitly name sibling tools or contrast with 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?

There is no explicit guidance on when to use this tool versus alternatives such as get_profile or get_career_timeline. The lived_only argument implies a filtering option, but the description does not state when an agent should choose this tool or what happens when lived_only is false beyond the initial sentence.

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, idempotentHint, and openWorldHint=false, so safety and side-effect profile is covered. The description adds useful context — the items are grouped by employer/school and the filter is a case-insensitive substring — but says nothing about result ordering, whether items are downloadable links vs metadata, or volume.

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 blocks: a purpose line and a docstring-style 'Args:' section. It is short, but the opening sentence is a list of contents rather than a lead statement of what the tool does, so the most important information is not front-loaded. The 'Downloadable' qualifier adds ambiguity rather than precision.

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-optional-parameter read-only listing tool with an output schema, the description supplies the domain vocabulary and filter semantics an agent needs. The remaining gap is resolving list-vs-download intent and unfiltered default behavior, which is modest for this complexity.

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 0% and the schema gives only a nullable string with no title help, so the description must carry the parameter. It does supply concrete example values ('Resume', 'MEARS', 'HP', 'Texas Tech', 'Other') and case-insensitive substring matching semantics, which is genuinely valuable, but it omits the default/no-filter behavior and whether an unknown group returns empty or an error.

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 describes the document collection ('Downloadable resume formats plus the portfolio: architecture diagrams, process docs, project write-ups, certificates, and college lab reports, grouped by employer/school') but never states the operation directly — no 'list'/'retrieve' verb, so an agent could plausibly read it as a download or a catalog tool. The resource is identifiable, but the action is only implied by the name.

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?

There is no guidance on when to call this versus siblings such as search, list_experience, or list_side_projects, and no statement of preconditions or exclusions. The only usage hint is the implicit 'omit group to get everything' behavior, which must be inferred from group being optional.

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, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: the results are sorted most-recent-first and each entry exposes an id, which is what an agent needs to plan the follow-up call.

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, both earning their place. Ordering is stated first and the id/follow-up detail second, so the most useful information is front-loaded with zero 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 zero-parameter, read-only list with an output schema that documents return values, the description covers purpose, ordering, and follow-up usage. Only minor gaps remain, such as whether an empty timeline is possible, which the output schema can reasonably carry.

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 no parameters, so the baseline is 4; the description correctly implies an unfiltered full listing rather than hinting at hidden filtering options. Nothing in it misleads about 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 identifies the resource ('career timeline') and its ordering ('most recent first'), which makes clear this is a listing tool. It also implicitly distinguishes itself from get_experience by noting entries carry ids 'for use with get_experience', though the verb itself is only conveyed by the tool name.

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 chaining guidance: call this to get the timeline, then use the per-entry id with get_experience for detail. That effectively routes the agent between two siblings. It stops short of a full when-not statement, but for a zero-parameter list tool the context is unambiguous.

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, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds only that each entry carries language, description, and a GitHub link, which is modest additional context rather than behavioral disclosure (no ordering, pagination, or empty-state 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?

A single short fragment with no wasted words, but it is under-specified rather than efficiently structured — there is no leading verb or scoping clause to anchor the reader, so brevity comes at the cost of clarity.

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 full annotations and an output schema, the description covers what is needed to select and invoke it. It only lacks a statement of purpose and any routing hint against the many sibling list/get tools.

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 the schema imposes no semantic burden and the baseline is 4. The listed fields are return-value information rather than parameter meaning, and the output schema already documents the response shape.

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 is a noun phrase that names the resource ('personal side projects') and the fields surfaced (language, description, GitHub link), which partially distinguishes it from siblings like list_experience. However, it never states the action (listing/retrieving), leaving the agent to infer the verb from the tool name alone.

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?

There is no guidance on when to call this versus alternatives such as list_experience or get_profile, and no indication of prerequisites or exclusions. The agent must infer that 'side projects' is distinct from professional experience purely from the wording.

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 cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the description's job is to add semantics, which it does: it discloses the AND-matching rule ("every word in the query must appear") and case-insensitivity. These are genuine behavioral facts an agent needs to craft queries, though ordering and result-count/truncation behavior are still unstated.

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 plus an examples clause, with the scope and matching rules front-loaded and no filler. Every sentence contributes either corpus definition or matching semantics.

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 search tool with annotations covering safety and an output schema covering return shape, the definition supplies what's needed to call it correctly: corpus scope, matching logic, and casing. Only minor gaps remain, such as ranking and whether results are truncated.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single `query` parameter, and it does: it defines the parameter as a keyword or phrase, gives three concrete example values, and specifies both tokenization (every word required) and casing behavior. The only gap is that phrase handling (quoting, stemming, substring vs whole-word) is not spelled out.

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 ("Search everything on kgromero.com") and enumerates the content domains covered (resume, skills, projects, documents, timeline, interests, travel), so an agent knows exactly what corpus is searched. It never names the sibling getters it competes with (get_skills, list_documents, etc.), so the differentiation is only implied by the word "everything".

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 broad scope suggests using this when you don't know which section holds the answer, and the sibling getters suggest the opposite. There is no explicit "use this instead of get_skills when..." routing instruction or exclusion, so the agent must infer the decision boundary.

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