Brent Burgess

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the response format is Markdown, and a fragment identifier yields only one section rather than the whole document. It does not say what happens for an unknown id, which is the only notable gap.

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 sentences, front-loaded with what is returned, then the id forms, then the anchor modifier. No filler, and each sentence adds a distinct piece of callable 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?

With a single fully documented parameter, complete annotations and an output schema covering the return shape, the description supplies everything an agent needs: what it reads, what formats the id accepts, and how to narrow to a section.

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, but the description earns more by enumerating concrete accepted id shapes with examples ('work/sleep-anchor', '/about', a brentburgess.com URL, a brentburgess:// URI, 'consulting'). That is more actionable than the schema's abstract list of forms.

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 resource (post, case study, page, project) and states exactly what comes back: full Markdown text, or one section of it. It relates itself to siblings by noting the id comes from search or list_content, which helps the agent place it in the workflow, though it never states outright how it differs in purpose from search or list_content.

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 read step after search or list_content, and that '#anchor' retrieves a single section. There is no explicit when-to-use/when-not clause or named alternative for reading vs listing, so the agent must infer the routing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context beyond that (no auth/permission notes, and the output schema covers what is returned), so it earns only baseline credit.

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, front-loaded with what the tool returns and followed by when to call it; every clause carries information. The content list is slightly long given the output schema presumably enumerates the same 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?

For a parameterless, read-only profile tool with a full output schema and comprehensive annotations, the description is essentially sufficient: an agent knows what it returns and when to prefer it. The loose thread is the absence of a pointer to sibling tools for non-profile questions.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly adds no parameter discussion.

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 (Brent Burgess's profile) and enumerates its contents: job title, introduction, location, availability, skills, contact info, and main site pages. That is far more specific than the title alone. It stops short of naming any sibling tool to differentiate from, so it does not reach a 5.

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 it first" gives an explicit ordering preference, and "for any question about contacting or hiring him" scopes the use case clearly. There is no stated when-not-to-use or named alternative (e.g., versus `fetch` or `search`), which keeps it below 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. It adds genuine behavioral semantics: the time windows each metric covers (since launch, latest complete week, nightly) and that each figure carries the last day its data covers, which tells the agent how fresh and how bounded the numbers are.

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: a content inventory followed by a routing pointer. The long enumeration is load-bearing because it defines the metric set, and the routing sentence is well placed at the end. It is dense but nothing is wasted.

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 statistics tool with an output schema that already documents the return shape, the description supplies everything else an agent needs: what metrics exist, their time windows, freshness semantics, and where to go for raw tables.

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 avoids inventing filtering options that the empty schema rejects.

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 enumerates precisely what the tool returns — page views, font downloads, crawlers/scans, commits, PRs, CI runs, pipeline tests and sources — and explicitly contrasts itself with query_dataset. It is a resource enumeration rather than a clean verb+resource phrasing, but an agent can identify the tool's scope without opening the schema.

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 names the alternative (query_dataset) and the condition that selects it ('for the tables behind them'), which is exactly the disambiguation an agent needs against that sibling. It gives no guidance on choosing between this tool and get_profile or the other list_* siblings, so it falls short of a full when/when-not treatment.

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 destructiveHint=false, so the safety profile is covered. The description still adds useful behavior beyond the annotations: results come back 'newest first' and each item includes its 'sections'. It omits any pagination or result-size limits.

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 with the scope and ordering front-loaded; nothing is padded. The second sentence is slightly garbled and could be read as describing this tool's parameters rather than the fetch tool's.

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?

An output schema exists, so return values need no explanation, and the description covers filtering, ordering and included sections. The residual gap is the ambiguous 'id' reference and no mention of result limits for a tool that lists everything.

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 single 'kind' enum is fully documented in the schema, so the description's restatement of the enum values adds nothing. Worse, it introduces an 'id' argument that does not exist in the schema ('Pass an id to fetch to read it'), which could mislead an agent into passing an unsupported parameter.

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 set ('Every post, case study and page the server can read') plus scope and ordering ('newest first'). It is clearly distinguishable from siblings like search or query_dataset, though it never names them to make the contrast explicit.

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?

'Filter with kind' and 'Pass an id to fetch to read it' imply when to use this tool versus the fetch tool for reading a single item, which is real routing guidance. However the phrasing is ambiguous — 'an id' is not a parameter of this tool — and there is no guidance on when to prefer search over listing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scope of returned data (status, changes, tools, case study) but says nothing about ordering, result size, or pagination behavior beyond the safety metadata.

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 tight sentence with no filler, and the resource is front-loaded before the filtering hint. The mid-sentence field enumeration is slightly list-like but each item conveys real content.

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-required-parameter list tool with an output schema, the description covers what is listed and how to filter, which is sufficient. It does not address ordering or result limits, a minor omission for a read-only listing call.

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 single status parameter is documented with its enum values in the schema, so the description is not required to carry parameter meaning. The mention of 'running' as an example filter is only marginal added value over the schema's enum.

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 identifies the resource — the projects on the site — and enumerates the aspects returned (status, changes, tools, case study). It is distinguishable from siblings like list_content or get_profile, though the phrasing is a noun list rather than a crisp verb+resource statement.

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 a concrete usage hint for the filter — 'Filter with status, for example "running"' — but says nothing about when to choose this over list_content, search, or query_dataset, or what happens when no filter is supplied.

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 destructiveHint=false, so the safety profile is covered without the description. The description still adds genuine behavioral context: oldest-first ordering, that truncation returns the most recent rows, and that daily/weekly tables retain about a year of history. That is meaningful extra disclosure, though permissions and pagination beyond the single limit are unaddressed.

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 tight sentences, each carrying distinct information: what is returned, how filtering and truncation work, and the retention bound. The scoping detail is front-loaded 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?

An output schema exists, so return-value explanation is unnecessary and the description correctly avoids it. For a 4-param, 12-enum read tool with full annotation coverage, the description supplies the behavioral and date-semantics context an agent needs. The only omission is explicit sibling routing, which keeps it off a 5.

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 even with no added param detail. The description does add one real semantic point the schema lacks: from and to apply to the table's date column, not an arbitrary one. It otherwise restates format information already present in the schema pattern and limit constraints.

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 resource (the rows of one table behind the site's data page) and its shape (columns with type and meaning), which clearly distinguishes it from list/search-style siblings. It never explicitly routes the agent away from siblings like fetch, search, or get_site_stats, so it falls short of a 5.

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 agent can infer this is the tool for reading raw table rows with date filters. There is no statement of when to use this versus get_site_stats, fetch, or search, and no prerequisites or exclusions are given. The schema's reference to get_site_stats hints at a relationship but the description itself offers no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds the useful result-shape behavior (results are sections, ids feed fetch), but since an output schema exists the return structure is largely redundant. No rate limits or query-length constraints mentioned beyond the schema.

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 sentences, front-loaded with scope, then keyword guidance, then the fetch handoff. The page enumeration is slightly long but each item earns its place by clarifying coverage. 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 search tool with an output schema, the description covers scope, input style, and the follow-up workflow, which is what an agent needs. Minor gaps: nothing about empty-result behavior or how `limit` truncates, though both are partly covered by the schema defaults.

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 baseline is 3; the description earns a bump by illustrating query keyword style and implicitly mapping the searchable content to the `kind` enum values (posts, case studies, pages, projects). It does not, however, explain how `kind` or `limit` interact with results, which the schema already handles.

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 scope: 'Full-text search over everything published,' then enumerates exactly what is covered (posts, case studies, pages, projects). An agent can distinguish this from list_content/list_projects (enumeration) and fetch (single-section retrieval) without opening the schema.

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?

Tells the agent how to phrase input ('Use plain keywords, such as "resumable upload"') and names the follow-up tool and its trigger ('pass its id to fetch to read it'). It also hints that work history lives on the résumé page. No explicit when-not to search guidance, 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.